Skip to content

Factory

Jump to bottom
Shesh Ghimire edited this page Jan 7, 2026 · 15 revisions

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:

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 the default CardType class when factory creates Card.

💡 Order priority for using concrete class (that accepts two parameters) when Cards are created:

  • The $payload data's classname Schema Key value
  • Globally set to the factory if not found in $payload
  • CardType base class if not found in factory
use TheWebSolver\Codegarage\PaymentCard\CardType;
use TheWebSolver\Codegarage\Test\Resource\NapasCard;
use TheWebSolver\Codegarage\PaymentCard\CardFactory;

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
// default "CardType" class unless global Card class is set again.
CardFactory::resetGlobalCardClass();

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

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

// Payload resource path in either PHP or JSON format.
$cards = CardFactory::createFromFile(path: $phpOrJsonFilePath);

// For lazyload version, use:
$lazyLoadedCards = CardFactory::createFromFile(path: $filePath, lazyload: true);

// For lazyload version without keys, 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 Requirement Polyfill
type string optional Credit Card
classname class-string<CardInterface> optional CardType
checkLuhn bool optional true
name string mandatory -
alias string mandatory -
breakpoint list<int> mandatory -
code array{name:string,size:int} mandatory -
length list<int|list<int>> mandatory -
idRange list<int|list<int>> mandatory -

Accepted Parameters

  • Concrete class (either from $payload or factory or base) accepts following two parameters via its constructor in the given order:
    1. $type
    2. $checkLuhn
  • Parameter 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.

Clone this wiki locally