Factory

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

Payload

It accepts following data-types to create Cards for you to use in your application:

1. (HIGHLY RECOMMENDED) a JSON file (can be an array of objects or a object of objects).
2. an array (can be an associative array) that contains an associative arrays of data.
3. a PHP file that has data in 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

You can use a concrete Payment Card class that will be instantiated when creating cards from your $payload.

⚡ If your $payload uses classname Schema Key to define custom classname, it'll override the globally set Card classname (Napas Card as in the example below).

use TheWebSolver\Codegarage\Test\Resource\NapasCard;

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

CardFactory::setGlobalCardClass(NapasCard::class);

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

// If you want to switch to an anonymous class from
// "NapasCard" class on subsequent card creation.
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 created as 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 (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 requesting key.
$lazyLoadedCards = $cardFactory->lazyLoadCards(preserveKeys: false);

All Cards

Via Factory Instance

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

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

$cards = $cardFactory->createCards();

In this case, $cards will be an indexed array with no keys preserved.

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

Via Static Methods

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


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

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

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

// For lazyload without keys version (in 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(); // The first element of the $payload.

if $payload is created as object of objects, then use that key to get a specific card.

$payload     = 'path/to/cards.json';
$cardFactory = (new CardFactory($payload));
$card        = $cardFactory->createCard('mastercard'); // The element in $payload with its key as "mastercard".

Schema

The payload data should follow the below schema:

Key	Data Type	Mandatory	Polyfill
type	string	optional	Credit Card
classname	string (class-string<CardInterface>)	optional	anonymous class[^global]
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

[^global]: If CardFactory::setGlobalCardClass() is used to define a concrete classname, it will be used instead of using an anonymous class that extends CardType. This concrete class accepts the type and checkLuhn Schema values (either user provided or polyfilled) Via its constructor which 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 you project needs specific class on per payload basis.