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.json';
$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	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

• 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 your project needs specific class on per payload basis.