thoemo
Repositories Projects Packages
7

thoemo/cards (1.4.1)

Published 2026-10-25 16:16:28 +00:00 by elnebuloso

Installation

{
	"repositories": [{
			"type": "composer",
			"url": ""
		}
	]
}
composer config repositories.thoemo composer 
composer require thoemo/cards:1.4.1

About this package

Playing Cards Library

thoemo/cards

Playing cards for PHP: cards, suits and values of the standard 52-card deck, card collections that can be shuffled, sorted, drawn from and combined, and dealing shoes made of several decks.

Requirements

  • PHP >= 8.2
  • thoemo/calc ^1.3.1 (installed automatically)

Installation

The package is served by the Forgejo Composer registry. Add the repository to your composer.json:

"repositories": {
    "packages.link.thoemo.net/thoemo": {
        "type": "composer",
        "url": "https://packages.link.thoemo.net/api/packages/thoemo/composer"
    }
}

Then require the package:

composer require thoemo/cards

The PHP namespace is Thoemo\Cards. Before 1.4 it was elnebuloso\Cards; update your use statements when upgrading.

Overview

Class Description
Card One card, made of a CardValue and a CardSuit; created with createByType() or createByValueAndType().
CardValue Card value 2 to 14 (VALUE_2 … VALUE_10, VALUE_JACK, VALUE_QUEEN, VALUE_KING, VALUE_ACE).
CardSuit Suit C, D, H, S (TYPE_CLUB, TYPE_DIAMOND, TYPE_HEART, TYPE_SPADE).
CardCollection Ordered list of cards: add, draw, shuffle, sort, merge, combinations; countable and iterable.
Deck Interface of all decks.
AbstractDeck Base class that builds a deck from the values and suits a subclass returns.
StandardDeck The 52-card deck (StandardDeck::TYPE = "standard").
DeckFactory create(string $type): Deck; knows StandardDeck::TYPE.
DealingShoe 2, 4, 6 or 8 decks of one type merged into one collection.

Invalid input (unknown type, name or value, wrong number of decks) throws an InvalidArgumentException.

Usage

Build a deck, shuffle and deal

A new StandardDeck is sorted from 2C to AS (value first, then suit). Drawing takes cards from the top.

use Thoemo\Cards\StandardDeck;

$deck = new StandardDeck();  // or (new DeckFactory())->create(StandardDeck::TYPE)
count($deck->getCards());    // 52

$deck->shuffle();            // 10 rounds of PHP's shuffle() by default, shuffle(3) for 3 rounds
$deck->isShuffled();         // true

$card = $deck->drawCard();   // Card
$hand = $deck->drawCards(5); // CardCollection
echo $hand;                  // e.g. "QH,3C,10S,AD,7H"
count($deck->getCards());    // 46

drawCards($n) returns all remaining cards if fewer than $n are left, so check the count of the result when the deck may run low.

Cards

A card type is the value (2–10, J, Q, K, A) followed by the suit letter.

use Thoemo\Cards\Card;
use Thoemo\Cards\CardSuit;
use Thoemo\Cards\CardValue;

$card = Card::createByType("10S");
// same card: Card::createByValueAndType(CardValue::VALUE_10, CardSuit::TYPE_SPADE)

$card->getType();                  // "10S" (also what (string) $card returns)
$card->getName();                  // "Ten of Spades"
$card->getValue();                 // 104: value followed by suit value (C=1, D=2, H=3, S=4), sortable
$card->getImage();                 // "10♠"
$card->getCodeChar();              // "🂪"
$card->getCodeHtml();              // "🂪"
$card->getCardValue()->getValue(); // 10
$card->getCardSuit()->getName();   // "Spade"

json_encode($card); // type, name, value, valueNormalized, image, codes, cardSuit, cardValue

CardValue and CardSuit can also be created on their own, by type, name or value:

CardValue::createByType("K"); // or createByName("King"), createByValue(13)
CardSuit::createByType("H");  // or createByName("Heart"), createByValue(3)

Card collections

use Thoemo\Cards\CardCollection;

$cards = new CardCollection([Card::createByType("9D"), Card::createByType("AD")]);
$cards->addCard(Card::createByType("QD"));

echo $cards->sortAsc();  // "9D,QD,AD" (returns a new collection)
echo $cards->sortDesc(); // "AD,QD,9D"

$all = $cards->merge(new CardCollection([Card::createByType("KC")])); // new collection, 4 cards

foreach ($all->combinations(3) as $combination) {
    echo $combination, " "; // each combination is a CardCollection
}
// 9D,AD,QD 9D,AD,KC 9D,QD,KC AD,QD,KC

count($all); // 4
foreach ($all as $card) {
    // $card is a Card
}

Dealing shoe

use Thoemo\Cards\DealingShoe;

$shoe = new DealingShoe(StandardDeck::TYPE, 6); // 2 decks if the count is omitted
count($shoe->getCards()); // 312
$shoe->shuffle();
$card = $shoe->getCards()->drawCard();

Custom decks

A deck with other cards extends AbstractDeck and implements getType(), getValues() (an array of CardValue::VALUE_*) and getSuites() (an array of CardSuit::TYPE_*). DeckFactory and DealingShoe only know StandardDeck.

Development

Tests and tools run through redo, the Docker-based CI wrapper; build.yml holds the project's redo properties (default PHP version 8.2).

redo composer:install phpunit                     # PHPUnit with the PHP version from build.yml
redo composer:install phpunit -Dphp_version=8.4   # PHPUnit with another PHP version
redo phplint -Dphp_version=8.4

The coverage report is written to build/reports/phpunit/all/coverage/html.

Releases

Every push to main runs the GitLab pipeline (phplint, prettier, composer:validate:require and PHPUnit on PHP 8.2 to 8.5), raises the patch version in VERSION and uploads that version to the Forgejo registry. The released archive contains only README.md, composer.json and src/.

Dependencies

Dependencies

ID Version
php >=8.2
thoemo/calc ^1.3.1
Details
Composer
2026-10-25 16:16:28 +00:00
5
2026-10-25 18:52:54 +00:00
proprietary
12 KiB
Assets (1)
thoemo-cards.1.4.1.zip 12 KiB
Versions (4) View all
1.4.1 2026-10-25
1.3.5 2026-10-25
1.3.4 2026-10-25
1.3.3 2026-10-25