README

Introduction

This library offers a few VO classes to use inside Card-related applications:

• Card: represents a Card, for example an ace of spades.
• Rank: represents the rank value of a Card, for example "A" or "7" ("T" is used for 10, to keep the same length).
• Suit: represents the card suit, for example spades or diamonds.

Some more classes, more elaborate, are available. They are abstract, and thus require a custom implementation to extend them:

• Hand: represents a set of Card objects, usually the ones assigned to a player
• HandsTrick: represents a trick of hands (think for example Poker, when players show their hands to declare a winner)
• CardTrick: represents a trick of cards (think for example the 4 cards of a Bridge turn)

Installation

Just use composer require garak/card.

Usage

Example:

<?php

require 'vendor/autoload.php';

use Garak\Card\Card;
use Garak\Card\Rank;
use Garak\Card\Suit;

$card = new Card(Rank::Ace, Suit::Diamonds);
echo $card; // will output "Ad"

$card = new Card(Rank::Seven, Suit::Spades);
echo $card->toText(); // will output "7♠"

$card = Card::fromRankSuit('Kh');
echo $card->toUnicode(); // will output "🂾"

You can also get a full deck:

<?php

require 'vendor/autoload.php';

use Garak\Card\Card;

$orderedCards = Card::getDeck();
$shuffledCards = Card::getDeck(shuffle: true);
$doubleDeckWithJokers = Card::getDeck(shuffle: true, num: 2, allowJokers: true);

Upgrading from version 0.8

Rank and Suit have been converted from regular classes to backed enums. The following breaking changes apply.

Instantiation

When you only have a string at runtime (e.g. from user input or persistence), use the enum's from() factory:

$rank = Rank::from('A');  // Rank::Ace
$suit = Suit::from('s');  // Suit::Spades

Invalid values

Previously invalid values threw \InvalidArgumentException. They now throw \ValueError (the standard PHP exception for invalid enum values):

// Before
try {
    new Rank('X');
} catch (\InvalidArgumentException $e) { ... }

// After
try {
    Rank::from('X');
} catch (\ValueError $e) { ... }

Use Rank::tryFrom('X') / Suit::tryFrom('X') to get null instead of an exception.

Iterating over all ranks or suits

The public static arrays Rank::$ranks and Suit::$suits have been removed. Use the standard enum cases() method instead:

// Before
foreach (Rank::$ranks as $symbol => $intValue) { ... }
foreach (Suit::$suits as $symbol => $unicodeChar) { ... }

// After
foreach (Rank::cases() as $rank) {
    $symbol   = $rank->value;    // e.g. 'A'
    $intValue = $rank->getInt(); // e.g. 14
}
foreach (Suit::cases() as $suit) {
    $symbol    = $suit->value;      // e.g. 's'
    $unicodeChar = $suit->toText(); // e.g. '♠'
}

Suit::$jokerColors has also been removed; joker suits are now Suit::BlackJoker and Suit::RedJoker.