Download the PHP package buffalokiwi/buffalotools_types without Composer

BuffaloKiwi Types

An extremely useful package containing Enum, BitSet, Set and BigSet types for PHP 7.4.

MIT License

Table of Contents

1. Installation
2. Enum / State Machine
3. Bit Set
4. Set
5. BigSet

Installation

Enum State Machine for PHP 7.4

Without extensions PHP is lacking an Enum type. This is a fast Enum implementation that doubles as a state machine.

Enum is abstract, and must be extended in order to create an enum. RuntimeEnum may be used to create Enum objects on the fly.

Here's an example of how to create an Enum implementation.

1. Create a class that extends Enum.
2. Add enum values as class constants and/or list the enum values in a protected array property named $enum.

Optionally, Enum can also contain additional values

Enum Usage

Create enum instance and initialize to KEY1

Create enum instance and initialize to KEY1

Create enum instance and initialize to KEY1

Test if an enum is equal to a certain value

Get an enum value

Set an enum value

Test if a member is valid

Test if an enum is equal to another enum of the same class type

Retrieve a map of enum constants to values

Retrieve a list of constants:

Listing all available enum values

Sorting a list of IEnum

Valued Enum

It's possible to attach arbitrary values to enum members. This is accomplished by initializing the $enum array property as a map where the keys are the enum keys and the values are the arbitrary values.

Usage:

Using the enum as a state machine

An enum is a natural fit for a state machine. The Enum implementation includes several methods to accomplish this. This essentially turns the enum into an indexed array with a reference to a single active value.

Get the index of an enum value:

With the index value, we can move next and previous. If next or previous is called when already at the end/beginning, then no action is taken.

Using the index value, we can implement greater than and less than.

Can compare using strings:

Test if the enum changed from some value to a different value:

If you simply want to know if the enum changed to some state at any time, then call changedTo().

Retrieve the change log. This is a log of every change the enum went through during it's lifetime.

Enum Events

Change events can be attached to the enum object or added to a class that descends from Enum.

If the enum implementation overrides onChange(), the same rules as above are followed. Throw an exception to roll back.

Creating Enum at runtime.

This can be accomplished by using the RuntimeEnum class.

For example, say we wanted to create an enum with two possible values, and set the initial value. We can do the following:

//..Create a new enum with two values and initialize to 'key1'

BitSet

BitSet is a a wrapper for a single integer, which can then be used as 32 or 64 individual boolean values, and contains methods for operating on the bits.

Create a new and empty BitSet. This will have either 32 or 64 possible values based on the architecture the installed PHP version.

Enable bits

Disable bits

Toggle bits

Testing if bits are enabled

Retrieving the internal value The internal value is the sum of all enabled bits

Set

While bit sets are useful, wouldn't it be great if we could name the bits? If you like naming things, and you want all your bits to have names, then look no further than the Set class!

The Set implementation is a BitSet with named bits.

Originally, this was designed to work with set column types in MySQL, and it can still be used for that!

Here's how it works:

1. Create a new class that descends from Set
2. Add class constants for each bit and set the value equal to some string value.
3. Add the constants to a protected array property named $members.

Creating the Set instance

Create a new set and enable zero bits

Create a new set and enable both bits

Create a new set and enable both bits

Enabling bits

Disabling bits

Retrieve the bit value

Testing bits

Test if all specified bits are valid members of the set

Test if a bit is enabled

Test if the set has zero bits enabled

Test if one or more values are enabled

Adding new Set members at runtime

Say you had a set with 2 members, and you forgot you really wanted 3. No problem! We can do crazy things like this:

Retrieving a list of the names of all available bits

Retrieving a list of all enabled bit names

If you want to retrieve the total value of the set (an integer representing all possible bits), you can call getTotal().

If you want to create a Set at runtime, and don't want to create a class, then use RuntimeSet.

Example:

Create a new Set with two bits named bit1 and bit2, and set bit1 to enabled:

It's also possible to add a value for each bit in a Set by using the MapSet class. This adds the get() method to ISet, and can be used to retrieve the value attached to a named bit.

Usage:

BigSet

A big set is a set that can handle more than 32 or 64 elements, but loses the ability to perform bitwise operations since the set is no longer backed by a single integer.

This is basically the same thing as an ISet, but without being backed by a BitSet.

Internally, this maintains a list of ISet instances and each member of the big set is mapped to a bit one of the internal sets.