Primordyx Framework Documentation

BlackHorse
in package

Static Price Encoding Utility for Retail Inventory Management

Provides a simple substitution cipher for encoding decimal prices into alphabetic codes, allowing retailers to display encoded cost information on price stickers that staff can decode but customers cannot easily understand.

Encoding System Overview

The encoding uses any 10-character word with unique letters where each letter maps to a digit (1-9, 0). Prices are converted to cent values and then encoded letter-by-letter.

Key Features

  • Substitution Cipher: Maps digits to letters using a customizable code word
  • Flexible Encoding Length: Supports various price ranges via configurable output length
  • Customer ID Encoding: Additional methods for encoding customer IDs with privacy offset
  • Method Chaining: Fluent interface for setting code word and encoding in one statement
  • Event Integration: Uses Primordyx EventManager for error reporting

Digit Mapping Example

For the default code word "BLACKHORSE":

  • B=1, L=2, A=3, C=4, K=5, H=6, O=7, R=8, S=9, E=0

Usage Patterns

Chained Style

$encoded = BlackHorse::setCodeWord('NIGHTCRAWL')->encode(12.34); // "EEBLAC"
$price = BlackHorse::decode('EEBLAC'); // 12.34

Separate Style

BlackHorse::setCodeWord('WORKINGDAY');
$encode1 = BlackHorse::encode(1234.56);
$encode2 = BlackHorse::encode(987.54);
$decode1 = BlackHorse::decode('EEBLAC');

Customer ID Encoding

BlackHorse::setCodeWord('BLACKHORSE');
$publicId = BlackHorse::encodeCustomerId(47);  // Adds offset of 25000
$customerId = BlackHorse::decodeCustomerId($publicId);  // Returns 47

Example Code Words

Any 10-character combination with unique letters works:

  • BLACKHORSE (default)
  • THUNDERBOX
  • NIGHTCRAWL
  • WORKINGDAY
  • PRODUCTKEY
  • MASTERLOCK

Maximum Encodable Values by Length

  • Length 4: Up to $99.99
  • Length 6: Up to $9999.99 (default)
  • Length 8: Up to $999999.99

Security Considerations

  • Not cryptographically secure - designed for staff/customer separation only
  • Should not be used for sensitive data protection
  • Code word changes affect all subsequent operations globally
Tags
see
EventManager

For error event handling

since
1.0.0

Table of Contents

Properties

$codeWord  : string
Current code word being used for encoding/decoding

Methods

decode()  : float
Decode an alphabetic code back to the original decimal price
decodeCustomerId()  : int
Decode a public customer ID back to the internal customer ID
encode()  : string
Encode a decimal price into an alphabetic code
encodeCustomerId()  : string
Encode a customer ID into a public-facing obfuscated ID
getCodeWord()  : string
Get the current code word being used for encoding/decoding
setCodeWord()  : string
Set the code word for subsequent encode/decode operations
validateCodeWord()  : void
Validate code word format

Properties

$codeWord

Current code word being used for encoding/decoding

private static string $codeWord = 'BLACKHORSE'

Methods

decode()

Decode an alphabetic code back to the original decimal price

public static decode(string $encoded) : float

Reverses the encoding process by converting each letter back to its corresponding digit using the current code word, then converting the resulting cent value back to decimal dollars.

Decoding Process

  1. Map each letter to digit: EELBAC → 001234
  2. Convert cents to dollars: 001234 → 12.34

Error Handling

Throws an exception if the encoded string contains any character that doesn't exist in the current code word. Also fires an event for logging purposes before throwing.

Parameters
$encoded : string

Encoded alphabetic price string of any length

Tags
since
1.0.0
static
throws
InvalidArgumentException

If encoded string contains characters not in code word

example

Successful Decoding

BlackHorse::setCodeWord('BLACKHORSE');
$price = BlackHorse::decode('EELBAC');  // Returns 12.34
example

Error Handling

try {
    $price = BlackHorse::decode('XYZ123');  // Invalid characters
} catch (InvalidArgumentException $e) {
    echo "Decoding failed: " . $e->getMessage();
}
fires

blackhorse.invalid_character When an invalid character is encountered

Return values
float —

The decoded price in decimal dollars (e.g., 12.34)

decodeCustomerId()

Decode a public customer ID back to the internal customer ID

public static decodeCustomerId(string $publicId) : int

Reverses the customer ID encoding by decoding the alphabetic string and removing the privacy offset to retrieve the original internal customer ID.

Error Handling

If the encoded public ID contains invalid characters, the underlying decode() method will throw an InvalidArgumentException. Consider wrapping calls in try-catch blocks when processing untrusted input.

Parameters
$publicId : string

The encoded public customer ID to decode

Tags
since
1.0.0
static
throws
InvalidArgumentException

If public ID contains invalid characters

example

Basic Usage

$customerId = BlackHorse::decodeCustomerId($publicId);  // Returns original ID
example

With Error Handling

try {
    $customerId = BlackHorse::decodeCustomerId($publicId);
    $customer = Customer::find($customerId);
} catch (InvalidArgumentException $e) {
    // Handle invalid public ID
    return response('Invalid customer reference', 400);
}
see
BlackHorse::encodeCustomerId()

For creating public customer IDs

Return values
int —

The original internal customer ID

encode()

Encode a decimal price into an alphabetic code

public static encode(float $price[, int $length = 6 ]) : string

Converts a decimal price (dollars.cents) into an encoded alphabetic string using the current code word as a substitution cipher. The price is first converted to cents, padded with leading zeros to the specified length, then each digit is mapped to its corresponding letter.

Encoding Process

  1. Convert price to cents: 12.34 → 1234
  2. Pad with zeros: 1234 → 001234 (for length 6)
  3. Map digits to letters: 001234 → EELBAC

Length Parameter Guidelines

  • Length 4: For prices up to $99.99
  • Length 6: For prices up to $9999.99 (default)
  • Length 8: For prices up to $999999.99
Parameters
$price : float

The decimal price to encode (e.g., 12.34 for $12.34)

$length : int = 6

Number of characters in output (default: 6)

Tags
since
1.0.0
static
example

Basic Encoding

$encoded = BlackHorse::encode(12.34);  // Returns "EELBAC" (6 chars)
example

Custom Length

$encoded = BlackHorse::encode(5.67, 4);   // Returns "ECHI" (4 chars)
$encoded = BlackHorse::encode(1234.56, 8); // Returns "EELBACHI" (8 chars)
Return values
string —

Encoded alphabetic price string of specified length

encodeCustomerId()

Encode a customer ID into a public-facing obfuscated ID

public static encodeCustomerId(int $customerId) : string

Adds a privacy offset to a customer ID before encoding it, making it suitable for use in public URLs, order references, or anywhere you need to reference a customer without exposing their actual database ID.

Privacy Offset

The method adds 25000 to the customer ID before encoding. This ensures:

  • Customer IDs don't start from obvious low numbers
  • The encoded result is longer and less guessable
  • Sequential customer IDs don't produce sequential codes
Parameters
$customerId : int

The internal customer ID to encode

Tags
since
1.0.0
static
example

Basic Usage

BlackHorse::setCodeWord('BLACKHORSE');
$publicId = BlackHorse::encodeCustomerId(47);
// Customer 47 becomes 25047, then encoded
example

URL Generation

$customerId = 1234;
$publicId = BlackHorse::encodeCustomerId($customerId);
$url = "https://example.com/customer/{$publicId}";
see
BlackHorse::decodeCustomerId()

For reversing this operation

Return values
string —

Encoded public customer ID string

getCodeWord()

Get the current code word being used for encoding/decoding

public static getCodeWord() : string

Returns the currently active code word. Useful for debugging or when you need to verify which code word is currently in use.

Tags
since
1.0.0
static
example 
$current = BlackHorse::getCodeWord();  // Returns "BLACKHORSE" or current word
Return values
string —

Current code word in uppercase

setCodeWord()

Set the code word for subsequent encode/decode operations

public static setCodeWord(string $codeWord) : string

Validates and sets a new code word that will be used for all subsequent encoding and decoding operations. The code word must contain exactly 10 unique letters. Converts the input to uppercase automatically.

Method Chaining

Returns the class name to enable fluent interface pattern:

$encoded = BlackHorse::setCodeWord('NIGHTCRAWL')->encode(12.34);

Global State Warning

Changing the code word affects ALL subsequent BlackHorse operations across the entire application until changed again.

Parameters
$codeWord : string

Code word containing exactly 10 unique letters

Tags
since
1.0.0
static
throws
InvalidArgumentException

If code word doesn't have exactly 10 unique letters

example

Basic Usage

BlackHorse::setCodeWord('THUNDERBOX');
example

Method Chaining

$encoded = BlackHorse::setCodeWord('NIGHTCRAWL')->encode(45.67);
fires

blackhorse.invalid_codeword When code word validation fails

Return values
string —

Returns class name for method chaining

validateCodeWord()

Validate code word format

private static validateCodeWord(string $codeWord) : void
Parameters
$codeWord : string

Code word to validate

Tags
since
1.0.0
throws
InvalidArgumentException

If validation fails


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results