PHPackages                             si2k63/php-texas-hold-em-evaluator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. si2k63/php-texas-hold-em-evaluator

ActiveLibrary[Utility & Helpers](/categories/utility)

si2k63/php-texas-hold-em-evaluator
==================================

A composer library for evaluating poker hands

v3.0.2(1y ago)4107↓100%1MITPHPPHP >=8.1

Since Dec 13Pushed 1y ago2 watchersCompare

[ Source](https://github.com/Si2k63/PHP-Texas-Hold-em-Evaluator)[ Packagist](https://packagist.org/packages/si2k63/php-texas-hold-em-evaluator)[ RSS](/packages/si2k63-php-texas-hold-em-evaluator/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (2)Versions (5)Used By (0)

PHP Texas Hold'em Hand Evaluator
================================

[](#php-texas-holdem-hand-evaluator)

Getting Started
---------------

[](#getting-started)

Simply install the package through composer using the command:

```
composer require si2k63/php-texas-hold-em-evaluator

```

Overview
--------

[](#overview)

A surprisingly fast Texas Hold'em hand evaluator written in PHP. Draw cards from the deck factory class (or instantiate specific ones) and pass them to the evaluate class to determine their rank in the form of an integer or a full text description.

### Deck Class

[](#deck-class)

This is a factory class that will generate, shuffle and deal a deck of 52 cards.

#### Instantiating the class:

[](#instantiating-the-class)

```
$deck = new Deck();

```

#### Shuffling the deck:

[](#shuffling-the-deck)

```
$deck->shuffle();

```

#### Drawing a card:

[](#drawing-a-card)

```
$card = $deck->draw();

```

#### Drawing a specific card

[](#drawing-a-specific-card)

```
$card = $deck->card(Rank::Ace, Suit::Diamonds);

```

#### Checking if a card is present in the deck:

[](#checking-if-a-card-is-present-in-the-deck)

```
if ($deck->contains(new Card(Rank::Ace, Suit::Diamonds)) {
	echo "The Ad is in the deck.";
} else {
	echo "The Ad is not in the deck.";
}

```

### Card Class

[](#card-class)

#### Instantiating a Card

[](#instantiating-a-card)

```
$card = new Card(Rank::Ace, Suit::Hearts);

```

#### Getting the unique value of a card

[](#getting-the-unique-value-of-a-card)

```
$card->getValue();

```

### Evaluator Class

[](#evaluator-class)

The evaluator class is an abstract class that accepts hand iterator classes through its add iterator method.

Currently there is a High Card Evaluator that extends this class and passes in the relevant iterator classes through its constructor.

#### Instantiating the high card class:

[](#instantiating-the-high-card-class)

```
$evaluator = new HighCardEvaluator();

```

#### Determining the rank of a collection of five cards

[](#determining-the-rank-of-a-collection-of-five-cards)

```
$hand = Hand::fromArray([
	new Card(Rank::Ace, Suit::Clubs),
	new Card(Rank::Ace, Suit::Spades),
	new Card(Rank::Ace, Suit::Diamonds),
	new Card(Rank::King, Suit::Clubs),
	new Card(Rank::Jack, Suit::Hearts)
]);

$evaluator = new HighCardEvaluator();
$result = $evaluator->evaluate($hand);

echo "Rank:" . $result->getRanking() . PHP_EOL;
echo "Name: $name" . $result->getName() . PHP_EOL;

```

#### Extending the Evaluator Class

[](#extending-the-evaluator-class)

It is possible to extend the evaluator class and make your own evaluator (e.g a low card hand evaluator for games like 2-7 Triple Draw).

You'd need to implement your own hand iterator, which passes low card hands in order of rank (highest to lowest) into your class.

Additional Examples
-------------------

[](#additional-examples)

The examples directory contains two example scripts of how this hand evaluator could be used.

#### Example 1 - hand.php

[](#example-1---handphp)

Deals two random five card hands and compares them to determine the winning hand.

#### Example 2 - equity.php

[](#example-2---equityphp)

Compares two starting hands from Texas Hold'em and deals all possible boards to determine what percentaege of the time each hand wins.

Requirements
------------

[](#requirements)

- PHP 8.1 (As enums are used for the Ranks and Suits)
- Composer

How It Works
------------

[](#how-it-works)

The library is built on the principle that the multiplication of two prime numbers always results in a number that cannot be produced by multiplying any other two numbers.

Each card's rank and suit are assigned a unique prime number in ascending order.

On initialisation the evaluation class enumerates through all 7462 possible groupings of poker hands from best to worst, calculating a unique identifier for each of them.

e.g. A \* K \* Q \* J \* T = 14535931 (Ace High Straight)

Those unique identifiers are stored in a rankings array, with the unique identifier's position in the array being used as the basis for its rank. The unique id for A Royal Flush will be at position 0 in the array, while the unique id for 7 5 4 3 2 of differing suits (the worst possible 5 card combination) will be at the last position.

In cases of where a hand containing cards that are all the same suit (e.g. straight flushes and flushes) the product is multiplied by the next available prime number (59) to ensure a unique number is produced.

e.g. A \* K \* Q \* J \* T \* 59 = 857619929 (A Royal Flush)

This allows the evaluator to distinguish between flush and non-flush hands.

Then, when a hand is passed to the class for evaluation, the unique identifier for all possible five card combinations of cards is calculated and checked against the rankings table to determine which has the highest rank.

#### A Few Benefits of Using Prime Numbers

[](#a-few-benefits-of-using-prime-numbers)

1. The order of the cards does not matter when determining their rank (e.g. K A J Q T produces the same result as A K Q J T).
2. It's pretty quick once the rankings array is populated all we're doing is finding the key of an integer stored in that array.

References
----------

[](#references)

[https://en.wikipedia.org/wiki/Poker\_probability](https://en.wikipedia.org/wiki/Poker_probability)

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance33

Infrequent updates — may be unmaintained

Popularity15

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

668d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/914e4624c46c253def1f61bbc2ba23d0246fff110439c274d8cb95bb3f7111ee?d=identicon)[Si2k63](/maintainers/Si2k63)

---

Top Contributors

[![Si2k63](https://avatars.githubusercontent.com/u/6586177?v=4)](https://github.com/Si2k63 "Si2k63 (39 commits)")

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/si2k63-php-texas-hold-em-evaluator/health.svg)

```
[![Health](https://phpackages.com/badges/si2k63-php-texas-hold-em-evaluator/health.svg)](https://phpackages.com/packages/si2k63-php-texas-hold-em-evaluator)
```

###  Alternatives

[aristath/ari-color

A PHP library for color manipulation in themes and plugins

6128.6k](/packages/aristath-ari-color)[symfony/ux-notify

Native notification integration for Symfony

1274.7k](/packages/symfony-ux-notify)[thestringler/manipulator

An OOP approach to string manipulation.

345.5k2](/packages/thestringler-manipulator)[hauntd/yii2-vote

Votes, likes, favorites.

383.1k](/packages/hauntd-yii2-vote)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)