Download the PHP package dprmc/cusip without Composer
On this page you can find all versions of the php package dprmc/cusip. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package cusip
CUSIP
A PHP library for validating and working with financial security identifiers.
This package validates:
- CUSIP identifiers
- ISIN identifiers
- SEDOL identifiers
It also includes helpers for extracting valid CUSIPs from pasted text, removing duplicates, identifying symbol types, calculating CUSIP check digits, and fixing a narrow class of common CUSIP transcription errors.
Requirements
- PHP 7.4 or newer
- Composer
The current source uses typed properties, so PHP 7.4+ is required.
Installation
Quick Start
CUSIP Validation
Use CUSIP::isCUSIP() to validate a single CUSIP.
isCUSIP() returns true only when the input:
- is not empty
- is exactly 9 characters after trimming surrounding whitespace
- contains only valid CUSIP characters
- has a valid check digit
- is not in the package's explicit ignore list
Surrounding whitespace is ignored:
The special CUSIP characters *, @, and # are supported:
Invalid check digits return false:
Extracting CUSIPs From Text
Use getValidCusipsFromString() when users paste a list of CUSIPs into a textarea or form field.
The parser splits on whitespace and commas, ignores empty values, and removes invalid CUSIPs.
Use getUniqueValidCusipsFromString() when duplicate valid CUSIPs should be collapsed:
Removing Invalid CUSIPs From an Array
Use removeInvalidCusips() when you already have an array of candidate values.
CUSIP Check Digits
Use getChecksumDigit() to calculate the check digit for an 8- or 9-character CUSIP value.
If the input length is shorter than 8 characters or longer than 9 characters, the method returns false.
Fixing Common CUSIP Transcription Errors
CUSIP identifiers do not use the letters I and O because they are easy to confuse with 1 and 0.
Use fixCusip() to normalize a CUSIP and attempt that replacement:
fixCusip():
- trims surrounding whitespace
- converts the value to uppercase
- returns the value unchanged if it is already valid
- replaces
Iwith1andOwith0 - throws
DPRMC\UnfixableCusipExceptionif the result is still invalid
ISIN Validation
Use isISIN() to validate an International Securities Identification Number.
The method validates the ISIN format and checksum.
SEDOL Validation
Use isSEDOL() to validate a Stock Exchange Daily Official List identifier.
The method validates the SEDOL length, character rules, and checksum.
Detecting Symbol Type
Use getSymbolType() when an input may be a CUSIP, ISIN, or SEDOL.
getSymbolType() checks the value in this order:
- CUSIP
- ISIN
- SEDOL
If the symbol cannot be identified, it throws DPRMC\UnknownSymbolException.
Ignored CUSIPs
The package maintains a small list of CUSIPs that are structurally valid but should be treated as invalid by this library:
Current ignored values:
240000000111322608
These values pass the checksum algorithm but are known to create false positives in downstream parsers.
API Reference
CUSIP::isCUSIP($cusip = null): bool
Returns whether a value is a valid CUSIP.
CUSIP::getValidCusipsFromString(string $string): array
Splits a string on whitespace and commas, then returns only valid CUSIPs.
CUSIP::getUniqueValidCusipsFromString($string): array
Returns valid CUSIPs from a string with duplicates removed and indexes reset.
CUSIP::removeInvalidCusips($cusips): array
Filters an array of candidate values down to valid CUSIPs.
CUSIP::containsInvalidCharacters($cusip): bool
Returns true when a value contains characters that are not valid in a CUSIP.
CUSIP::getChecksumDigit($cusip): int|false
Calculates a CUSIP check digit. Returns false when the input length is invalid.
CUSIP::isISIN($isin): bool
Returns whether a value is a valid ISIN.
CUSIP::isSEDOL($sedol): bool
Returns whether a value is a valid SEDOL.
CUSIP::fixCusip(string $originalCUSIP): string
Returns a valid normalized CUSIP or throws DPRMC\UnfixableCusipException.
CUSIP::getSymbolType(string $symbol): string
Returns CUSIP, ISIN, or SEDOL. Throws DPRMC\UnknownSymbolException when the value is not recognized.
Exceptions
DPRMC\UnfixableCusipException
Thrown by fixCusip() when a value cannot be converted into a valid CUSIP.
The original value is available on:
DPRMC\UnknownSymbolException
Thrown by getSymbolType() when a value is not a valid CUSIP, ISIN, or SEDOL.
The original value is available on:
Development
Install dependencies:
Run the test suite:
Regenerate Composer's autoloader after adding or renaming classes:
Background
CUSIP stands for Committee on Uniform Securities Identification Procedures. CUSIPs are commonly used to identify North American financial securities.
More background is available on Wikipedia:
https://en.wikipedia.org/wiki/CUSIP
License
This package is released under the MIT License. See LICENSE.