Download the PHP package monospice/spicy-identifiers without Composer

Spicy Identifiers

An easy way to parse and manipulate identifier names, such as dynamic method names.

This package improves the experience of working with dynamic identifier names such as dynamically accessed methods and variables/properties. It also eases conversion between identifer case formats like camelCase and snake_case.

For instance, imagine that we have a configuration file that contains an array of configuration directives and a class that consumes those directives. If we write the configuration keys in snake_case, but the class uses camelCase to define corresponding setter methods, we can use this package to bridge the two more easily. See below for an example.

Note: The current stable version only includes support for working with dynamic methods and functions. Support for classes, variables, and properties is under development.

Simple Examples

Developers often use PHP's magic methods to dynamically overload class methods for more flexible functionality. This package can simplify the work needed to handle the dynamic method call:

Consider another example with a class that consumes configuration directives stored as an array. The configuration keys are written in snake_case, but the class uses camelCase to define corresponding setter methods. This package makes it easy to load the configuration:

Installation

We'll need to make sure to import the classes we want to use:

This package automatically installs the related Spicy Identifier Tools package of classes in the namespace Monospice\SpicyIdentifiers\Tools.

Types of Identifiers

This package provides different classes for working with various types of identifiers:

• DynamicIdentifier: A generic class that manipulates identifier names but provides no additional functionality
• DynamicMethod: Provides methods and defaults that expedite the process of working with class methods
• DynamicFunction: Provides methods and defaults that expedite the process of working with standard functions
• DynamicVariable: Provides methods and defaults that expedite the process of working with variables
• DynamicClass: Provides methods and defaults that expedite the process of working with classes

Parsing Identifer Names

To begin working with an identifier string, such as a method name, use one of the package's factory methods to parse it into the object:

The ::parse() factory method uses the default case format for the identifer type represented by each of the package's classes. To parse an identifier in a specific format, use the respective parsing method:

In addition to ::parse(), we can use the following factory methods from any of the DynamicIdentifier subclasses in this package to parse identifiers in a specific format:

• parseFromCamelCase() - Identifiers like: anIdentifierName
• parseFromCamelCaseExtended() - Identifiers like: änÏdentifierNáme
• parseFromUnderscore() - Identifiers like: an_identifier_name
• parseFromSnakeCase() - Alias for parseFromUnderscore()
• parseFromHyphen() - Identifiers like: an-identifier-name
• parseFromMixedCase() - Identifiers like: aMixed_case-identifier

For more information about identifier case formats and mixed-case or extended ASCII identifiers, see below.

Loading an Identifier

Sometimes we may wish to use the dynamic features of the classes in this package, but we don't need to parse the identifier string into its component parts. In these cases, we can avoid invoking the parser by using the ::from() factory method to simply create an instance for the identifier string to improve performance.

Similarly, in some cases we may already know or have the set of identifier parts that we'd like to use. We can call the ::fromParts() factory method to create an instance for the represented identifier:

Identifier Manipulation

After parsing an identifier, we can use this package to manipulate the parts. Let's use this DynamicIdentifier instance for the following examples:

At any time, we can retrieve the current identifier name:

name() - get the string representation of the entire identifier name

Alternatively, we can cast the dynamic identifer instance to a string:

Getting Identifer Part Data

parts() - get an array of identifier part names

part() - get the string value of the specified identifier part

Alternatively, use array access to get the value:

Note that the array of parts is zero-based, so the first part corresponds to the index 0.

first() - get the value of the first identifier part

last() - get the value of the last identifier part

keys() - get an array of identifier part indices

We can pass a string to the keys() method to get an array of indices with parts that match the value:

Note that keys() performs a case-insensitive comparison by default. To match the exact case, set the second parameter to true:

getNumParts() - get the number of identifier parts

Alternatively, use PHP's count() function to get the number of identifier parts:

Checking Identifer Parts

has() - check if the identifier contains a part at the specified index

One may use array access for the above as well:

startsWith() - check if the identifier starts with the specified string

endsWith() - check if the identifier ends with the specified string

Note that startsWith() and endsWith() perform case-insensitive comparisons by default. To match the exact case, set the second parameter to true:

Adding Parts

append() - add a part to the end of the identifier

Alternatively, use array access to push a part to the end of the identifier:

prepend() - add a part to the beginning of the identifier

insert() - add a part to the specified position in the identifier

Removing Parts

pop() - remove a part from the end of the identifier

shift() - remove a part from the beginning of the identifier

remove() - remove a part at the specified position of the identifier

Replacing Parts

replace() - replace a part at the specified position of the identifier

Alternatively, use array access to replace a part at the specified index:

Merging Parts

Merging parts doesn't change the output string, but combines parts of the internal array. This is useful for other operations.

mergeRange() - combine identifier parts between the specified positions

If one does not specify an ending position, any remaining parts after the starting position will be merged.

Dynamic Methods

The DynamicMethod class adds functionality for working with an underlying class method that corresponds to the parsed identifier name.

existsOn() - check if the represented method exists in the given class context

callOn() - call the method represented by the parsed method name in the given context

callFromScopeOn() - call the method represented by the parsed method name in the given context from the scope of that context

This method is similar to callOn(), but it permits access to private and protected methods that the DynamicMethod instance cannot call directly. callFromScopeOn() is intented for cases where DynamicMethod is used inside a class that could otherwise normally access its private and protected members directly. One should consider this use carefully before choosing this method, and always use callOn() for public methods.

forwardStaticCallTo() - forward the call to the static method represented by the parsed method name in the given context for late static binding

throwException() - throw a BadMethodCallException. The default exception message assumes that the exception is thrown becuase the method does not exist

One may specify the exception message in the first parameter:

throwExceptionIfMissingOn() - throw a BadMethodCallException if the method does not exist in the given context

One may specify the exception message in the second parameter:

Dynamic Functions

The DynamicFunction class adds functionality for working with an underlying standard function that corresponds to the parsed identifier name.

exists() - check if the represented function exists

call() - call the function represented by the parsed function name

throwException() - throw a BadFunctionCallException. The default exception message assumes that the exception is thrown becuase the function does not exist

One may specify the exception message in the first parameter:

throwExceptionIfMissing() - throw a BadFunctionCallException if the function does not exist

One may specify the exception message in the first parameter:

Changing Dynamic Identifier Types

We can obtain a particular identifer type from any of the Dynamic Identifier classes in this package. For example, a developer can get the DynamicVariable representation of a DynamicMethod with the same identifier name, but with methods specific to variables:

Note that this functionality does not cast the original object, but returns a new instance of the corresponding class. Because of this, remember to assign the returned object to a variable if you plan to use the converted instance later in the code. This design encourages proper variable names for each type.

The available conversions are:

Method Chaining

Methods that do not return an output value can be chained:

Identifier Case Formats

Each class uses a default case format to parse and output identifiers. These formats are constants set on the Tools\CaseFormat class.

For more information about the supported case formats, see the Spicy Identifier Tools package which this package includes automatically.

To override this default formatting, parse the identifier using one of the dedicated methods and/or set the output formatting explicitly:

Acronyms in Identifier Names

Sometimes identifier names contain acronyms, such as XML in JavaScript's XMLHttpRequest. The parsing methods preserve these acronyms:

However, the output methods will not preserve these acronyms unless we set an output format that preserves acronyms:

This behavior provides flexibility when converting or normalizing identifier names.

Identifiers with Mixed Case Formats

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

The package does not provide support to output identifiers in a mixed format. Any output methods will format the output string using the default format unless explicitly specified (see preceding section).

Extended ASCII Identifiers (Experimental)

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

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 Identifiers package provides an experimental method to parse these identifiers:

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 Identifiers package uses PHPSpec to test object behavior.

License

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