README

An easy way to parse, convert, and format identifier names.

These tools are helpful when working with dynamic identifier names such as dynamic methods or when working between different programming languages.

Simple Example

$identifierParts = Parser::parseFromUnderscore('an_identifier_name');
// returns array('an', 'identifier', 'name');

echo Formatter::formatCamelCase($identifierParts);
// 'anIdentifierName'

Or just:

echo Converter::convert(
    'an_identifier_name',
    CaseFormat::UNDERSCORE,
    CaseFormat::CAMEL_CASE
);
// 'anIdentifierName'

Installation

$ composer require monospice/spicy-identifier-tools

If you're autoloading classes (hopefully):

use Monospice\SpicyIdentifiers\Tools\CaseFormat;
use Monospice\SpicyIdentifiers\Tools\Parser;
use Monospice\SpicyIdentifiers\Tools\Formatter;
use Monospice\SpicyIdentifiers\Tools\Converter;

Basic Usage

The package comes with three tools:

Parser: Converts identifier strings into arrays of parts
Formatter: Comverts an array of identifier parts into a formatted string
Converter: Parses and formats an identifier string in one step

Parser

Parser::parseFromCamelCase('anIdentifier');     // array('an', 'Identifier');
Parser::parseFromUnderscore('an_identifier');   // array('an', 'identifier');
Parser::parseFromHyphen('an-identifier');       // array('an', 'identifier');

// or use the generic method:
Parser::parse('anIdentifier', CaseFormat::CAMEL_CASE);
// array('an', 'Identifier');

Note: Although PHP doesn't support hyphens in identifier names, the hyphen methods may be useful when working between other languages that do, like HTML/CSS or Lisp (gasp!).

Formatter

$parts = array('an', 'identifier');

Formatter::formatUppercase($parts);         // 'ANIDENTIFIER'
Formatter::formatLowercase($parts);         // 'anidentifier'
Formatter::formatCamelCase($parts);         // 'anIdentifier'
Formatter::formatUpperCamelCase($parts);    // 'AnIdentifier'
Formatter::formatUnderscore($parts);        // 'an_identifier'
Formatter::formatUpperUnderscore($parts);   // 'An_Identifier'
Formatter::formatCapsUnderscore($parts);    // 'AN_IDENTIFIER'
Formatter::formatHyphen($parts);            // 'an-identifier'
Formatter::formatUpperHyphen($parts);       // 'An-Identifier'
Formatter::formatCapsHyphen($parts);        // 'AN-IDENTIFIER'

// or use the generic method:
Formatter::format($parts, CaseFormat::CAPS_UNDERSCORE); // AN_IDENTIFIER

Converter

At this time, the Converter class only provides a generic method:

// Converter::convert($partsArray, $inputFormat, $outputFormat);

Converter::convert(
    'anIdentifierName',
    CaseFormat::CAMEL_CASE,
    CaseFormat::UPPER_CAMEL_CASE
);
// 'AnIdentifierName'

Case Formats

The CaseFormat class contains constants that represent each case.

This package supports the following "cases" for identifiers:

Note: Because the Parser class does not perform formatting, when using the ::parse() method, one must choose a "base" case to parse from, such as CAMEL_CASE, not UPPER_CAMEL_CASE or CAMEL_CASE_WITH_ACRONYMS.

Acronyms in Identifier Names

Sometimes identifier names contain acronyms, such as JavaScript's XMLHttpRequest. The Parser class preserves these acronyms:

$parts = Parser::parseFromCamelCase('XMLHttpRequest');
// array('XML', 'Http', 'Request');

However, the Formatter and Converter classes will not preserve these acronyms unless one chooses an output format with acronyms:

Formatter::formatCamelCase($parts);             // 'xmlHttpRequest'
Formatter::formatCamelCaseWithAcronyms($parts); // 'XMLHttpRequest'

This behavior provides flexibility when converting or normalizing identifier names.

Identifiers with Mixed Case

Although mixed case identifiers are not recommended in practice, one may use the Parser to parse identifiers that contain multiple cases:

// Parser::parseFromMixedCase($identiferString, $arrayOfCases);

Parser::parseFromMixedCase('aMixed_case-identifier', [
    CaseFormat::CAMEL_CASE,
    CaseFormat::UNDERSCORE,
    CaseFormat::HYPHEN,
]);
// array('a', 'Mixed', 'case', 'identifier');

The package does not provide support to output identifiers in a mixed format.

Extended ASCII Identifiers (Experimental)

PHP supports extended ASCII characters in identifier names. For example, the character ä in:

// From the php.net manual:
$täyte = 'mansikka';    // valid; 'ä' is (Extended) ASCII 228.

When parsing identifiers by underscore or hyphen, these characters have no effect. However, camel case identifiers may include words that are delimited by extended ASCII characters, such as änÏdentifierNáme.

The Spicy Identifier Tools package provides an experimental method to parse these identifiers:

Parser::parseFromCamelCaseExtended('änÏdentifierNáme');
// array('än', 'Ïdentifier', 'Náme');

The consistency of this method depends on the character encoding of the source files and the environment language and encoding settings. As a best practice, one should avoid using extended ASCII characters in identifier names.

For more information, visit the PHP Manual: http://php.net/manual/en/language.variables.basics.php

Testing

The Spicy Identifier Tools package uses PHPUnit to test input variations and PHPSpec for object behavior.

$ phpunit
$ vendor/bin/phpspec run

License

The MIT License (MIT). Please see the LICENSE File for more information.

monospice / spicy-identifier-tools

Maintainers

Details