README

A lightweight PHP library for analyzing and categorizing character types within strings. Easily count vowels, consonants, digits, special characters, and more.

Features

📊 Character Counting - Count vowels, consonants, numbers, and special characters
🔤 Case Analysis - Separate uppercase and lowercase letter counting
📈 Word Statistics - Calculate average word length in text
🎯 Result Storage - Automated collection and retrieval of analysis results
🚀 Zero Dependencies - No external dependencies required
✅ PSR-4 Compliant - Follows PSR-4 autoloading standards
🧪 Fully Tested - Comprehensive PHPUnit test suite included

Installation

Install via Composer (recommended):

composer require rodrigomanara/alpha

Or add to your composer.json:

{
    "require": {
        "rodrigomanara/alpha": "^1.1"
    }
}

Then run:

composer install

Requirements

PHP 7.1 or higher
Composer

Quick Start

<?php
require 'vendor/autoload.php';

use Manara\Alpha\Alpha;

$alpha = new Alpha();

// Analyze a string
$string = "Hello World 123!";

// Count different character types
$vowels = $alpha->checkVowels($string);       // Returns: 3 (e, o, o)
$consonants = $alpha->checkConsonates($string); // Returns: 7 (H, l, l, W, r, l, d)
$numbers = $alpha->checkNumber($string);      // Returns: 3 (1, 2, 3)
$special = $alpha->noalpha($string);          // Returns: 2 (space, !)
$uppercase = $alpha->upper($string);          // Returns: 2 (H, W)
$lowercase = $alpha->lower($string);          // Returns: 8 (e, l, l, o, o, r, l, d)

// Get average word length
$average = $alpha->calculateWordLetterAverage("hello world php"); // Returns: 5

// Retrieve collected results
$results = $alpha->getAll();  // Get all collected data
print_r($results);

Usage Examples

Basic Character Counting

$alpha = new Alpha();

// Count vowels
$vowelCount = $alpha->checkVowels("javascript");
// Result: 3 (a, a, i)

// Count consonants
$consonantCount = $alpha->checkConsonates("javascript");
// Result: 7 (j, v, s, c, r, p, t)

// Count numeric digits
$digitCount = $alpha->checkNumber("abc123def456");
// Result: 6 (1, 2, 3, 4, 5, 6)

Case Analysis

$alpha = new Alpha();

$upperCount = $alpha->upper("PHPisFun");      // Returns: 3 (P, H, P)
$lowerCount = $alpha->lower("PHPisFun");      // Returns: 5 (i, s, u, n)

Special Characters

$alpha = new Alpha();

// Count non-alphanumeric characters (spaces, punctuation, symbols)
$specialCount = $alpha->noalpha("Hello, World!");
// Result: 2 (comma, space, exclamation)

Word Statistics

$alpha = new Alpha();

// Calculate average characters per word (rounded up)
$average = $alpha->calculateWordLetterAverage("I am testing this library");
// Words: I(1), am(2), testing(7), this(4), library(7)
// Average: (1+2+7+4+7)/5 = 4.2 → rounds to 5

Working with Results

$alpha = new Alpha();

// Analyze and store results
$alpha->checkVowels("hello");
$alpha->checkNumber("abc123");

// Retrieve specific results
$vowels = $alpha->get('vowels');        // Array of vowels found
$numbers = $alpha->get('numbers');      // Array of numbers found

// Get all collected results
$allResults = $alpha->getAll();
// Output:
// [
//     'vowels' => ['e', 'o', 'o'],
//     'numbers' => ['1', '2', '3']
// ]

Complete Analysis Workflow

<?php
use Manara\Alpha\Alpha;

$alpha = new Alpha();
$input = "PHP 8.1 is awesome!";

// Perform complete analysis
$vowels = $alpha->checkVowels($input);
$consonants = $alpha->checkConsonates($input);
$numbers = $alpha->checkNumber($input);
$special = $alpha->noalpha($input);
$uppercase = $alpha->upper($input);
$lowercase = $alpha->lower($input);

// Display summary
echo "Analysis of: '$input'\n";
echo "Vowels: $vowels\n";
echo "Consonants: $consonants\n";
echo "Numbers: $numbers\n";
echo "Special Characters: $special\n";
echo "Uppercase: $uppercase\n";
echo "Lowercase: $lowercase\n";

// View detailed results
$results = $alpha->getAll();
echo "Detailed Results:\n";
print_r($results);

API Reference

Character Analysis Methods

`checkVowels(string $string): int`

Counts lowercase vowels (a, e, i, o, u) in the given string.

Parameter: $string - The input string to analyze
Returns: Integer count of vowels found

`checkConsonates(string $string): int`

Counts lowercase consonants (non-vowel letters) in the given string.

Parameter: $string - The input string to analyze
Returns: Integer count of consonants found

`checkNumber(string $str): int`

Counts numeric digits (0-9) in the given string.

Parameter: $str - The input string to analyze
Returns: Integer count of digits found

`upper(string $string): int`

Counts uppercase letters (A-Z) in the given string.

Parameter: $string - The input string to analyze
Returns: Integer count of uppercase letters found

`lower(string $string): int`

Counts lowercase letters (a-z) in the given string.

Parameter: $string - The input string to analyze
Returns: Integer count of lowercase letters found

`noalpha(string $string): int`

Counts non-alphanumeric characters (special characters, spaces, punctuation) in the given string.

Parameter: $string - The input string to analyze
Returns: Integer count of special characters found

`calculateWordLetterAverage(string $string): int`

Calculates the average number of characters per word in the given string.

Parameter: $string - The input string containing words
Returns: Integer average (rounded up) using ceil()

Result Management Methods

`set(string $key, string $value): void`

Stores or accumulates character findings by type.

Parameter: $key - The character type identifier
Parameter: $value - The character to store

`get(string $key): array`

Retrieves stored characters of a specific type.

Parameter: $key - The character type identifier
Returns: Array of characters, or empty array if not found

`getAll(): array`

Retrieves all collected character results.

Returns: Associative array of all character collections

Testing

This library includes a comprehensive test suite with 30+ tests covering all functionality.

Running Tests

First, install development dependencies:

composer install

Run all tests:

composer test

Run tests with coverage report:

composer run test:coverage

View test documentation:

cat TESTING.md

Important Notes

Character Case Sensitivity

The library only counts lowercase vowels and consonants (a-z, not A-Z). Use the upper() and lower() methods separately for case analysis.

Examples

// Lowercase vowels only:
$alpha->checkVowels("HELLO");      // Returns: 0
$alpha->checkVowels("hello");      // Returns: 2 (e, o)

// Use lower() for lowercase letter counting:
$alpha->lower("HeLLo");            // Returns: 2 (e, o)
$alpha->upper("HeLLo");            // Returns: 3 (H, L, L)

Method Naming

Note: The method is named checkConsonates (not "checkConsonants") for historical reasons, but functions identically to a consonant counter.

Performance

Lightweight: Zero external dependencies
Efficient: Uses native PHP functions for character analysis
Memory: Minimal memory footprint, suitable for batch processing

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Rodrigo Manara

Email: me@rodrigomanara.co.uk
GitHub: rodrigomanara

Contributing

Contributions are welcome! To contribute:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please ensure:

All tests pass (composer test)
Code follows PSR-12 standards
New features include test coverage
Documentation is updated accordingly

Changelog

Version 1.1.3

Current stable release
Full test suite included
Comprehensive documentation

Support

For issues, feature requests, or questions:

Open an issue on GitHub
Check existing issues for solutions
Review the TESTING.md and AGENTS.md files for development guidance

Roadmap

Performance optimizations for large texts
Unicode character support
Multi-language vowel detection
Additional character classification methods

Ready to use! Install via Composer and start analyzing strings today.

rmanara / alpha

Maintainers

Package info

Statistics

Security