Factory

Factory is one of the core API to generate Payment Cards based on the payload data that follows CardFactory Schema.

Payload

It accepts following data-types to create Cards:

1. (HIGHLY RECOMMENDED) a JSON file (can be an array of objects or a object of objects).
2. an indexed or associative PHP array that contains an associative arrays.
3. a PHP file that has data format described in #2 but returns:
   • data itself (RECOMMENDED).
   • a closure.
   • an invocable anonymous class.

Via Constructor

$payload     = 'path/to/cards.json';
$cardFactory = new CardFactory($payload);

Via Method

$payload     = 'path/to/cards.json';
$cardFactory = (new CardFactory())->withPayload($payload);

Set/Reset Global Card Class

Concrete Payment Card class can be used that will be instantiated instead of an anonymous class when factory creates Card.

⚡ If $payload data has classname Schema Key to define its own classname, it'll override this globally set Concrete Payment Card class (Napas Card as in the example below).

use TheWebSolver\Codegarage\Test\Resource\NapasCard;

CardFactory::setGlobalCardClass(NapasCard::class);

$payload     = 'path/to/cards.json';
$cardFactory = new CardFactory($payload);

foreach ($cardFactory->createCards() as $card) {
    $isNapasCardInstance = $card instanceof NapasCard; // true
}

// Globally set "NapasCard" class can be cleared. It will fallback
// to an anonymous class unless global Card class is set again.
CardFactory::resetGlobalCardClass();

foreach ($cardFactory->createCards() as $card) {
    $isNapasCardInstance = $card instanceof NapasCard; // false
}

Create Card(s)

LazyLoaded Cards

$payload     = 'path/to/cards.json';
$cardFactory = new CardFactory($payload);

if $payload is an object of objects, $lazyLoadedCards can access the key also.

$lazyLoadedCards = $cardFactory->lazyLoadCards();
$card1           = $lazyLoadedCards->current();   // First resolved Card instance.
$card1Key        = $lazyLoadedCards->key();       // First key of the resolved Card instance.

$lazyLoadedCards->next();                         // Move to second Card.

$card2 = $lazyLoadedCards->current();             // Second resolved Card instance.

$lazyLoadedCards->next();                         // Move to third Card.

// ...and so on unless all Cards are loaded. This
// is just for demonstration. In real usage,
// maybe wrap it in a while loop.
if ( $lazyLoadedCards->valid() ) {
    $cardN = $lazyLoadedCards->current();         // Last resolved Card instance.

    $lazyLoadedCards->next();
} else {
    $cardN = $lazyLoadedCards->current();         // null.
}

// Without preserving keys.
$lazyLoadedCards = $cardFactory->lazyLoadCards(preserveKeys: false);

All Cards

Via Factory Instance

$payload     = 'path/to/cards.json';
$cardFactory = new CardFactory($payload);

if $payload is an object of objects, then keys will be preserved and $cards will be an associative array.

$cards = $cardFactory->createCards();

But this feature can be disabled by passing parameter preserveKeys value as false.

$cards = $cardFactory->createCards(preserveKeys: false);

Via Static Methods

$phpFilePath = 'path/to/phpPayload.php';
$cards       = CardFactory::createFromPhpFile(path: $phpFilePath);


$jsonFilePath = 'path/to/jsonPayload.json';
$cards        = CardFactory::createFromJsonFile(path: $jsonFilePath);

// Alternatively, use:
$cards = CardFactory::createFromFile(path: $phpOrJsonFilePath);

// For lazyload version (applies any of the above static methods), use:
$lazyLoadedCards = CardFactory::createFromFile(path: $filePath, lazyload: true);

// For lazyload without keys version (applies any of the above static methods), use:
$lazyLoadedCards = CardFactory::createFromFile(path: $filePath, preserveKeys: false, lazyload: true);

Single Card

$payload     = 'path/to/cards.json';
$cardFactory = new CardFactory($payload);
$card        = $cardFactory->createCard(); // Using $payload first block of JSON object data.

if $payload is an object of objects, then object key can be used to get a specific Card.

$payload     = 'path/to/cards.json';
$cardFactory = new CardFactory($payload);
$card        = $cardFactory->createCard('mastercard'); // Using $payload block of JSON object data whose key is "mastercard".

Schema

The payload data must follow the schema described below to create Card instance:

Key	Data Type	Mandatory	Polyfill
type	string	optional	Credit Card
classname	class-string<CardInterface>	optional	anonymous class
checkLuhn	bool	optional	true
name	string	required	N/A
alias	string	required	N/A
breakpoint	array<string|int>	required	N/A
code	array{0:string,1:int}	required	N/A
length	array<int,string|int|array<int,string|int>>	required	N/A
idRange	array<int,string|int|array<int,string|int>>	required	N/A

Anonymous Class

• Anonymous class is an unnamed class that extends abstract CardType class to create a one-off object.
• If CardFactory::setGlobalCardClass() is used to define a concrete classname, this global classname will be used instead of an anonymous class.
• Both anonymous as well as globally set class accepts following two parameter values via its constructor:
  • $type
  • $checkLuhn These values can either be from the payload or polyfilled if not found in the payload. These values can then be accessed via their respective getter methods.
• When CardFactory::setGlobalCardClass() is used, CardFactory::resetGlobalCardClass() can also be used once Cards creation process is finished if the project needs specific class on per payload basis.