Here’s the most basic form

enum MaritalStatus {
  case Single;
  case Married;
  case Divorced;
  case Separated;
  case Widowed;
}

So now you can do

$employeeMaritalStatus = MaritalStatus::Married;

and

if ($employeeMaritalStatus == MaritalStatus::Married) {
  echo 'Employee is married';
}

You can’t do

echo $employeeMaritalStatus;

because an enum isn’t a string, and it’s not automatically convertible into a string, but you can do

echo $employeeMaritalStatus->name;

which will get you a string value like “Married”, “Single”, etc.

The first thing you might want to do is produce a human-readable display version of that, e.g. “Divorced/Civil Partnership Dissolved” instead of “Divorced”.

That’s called a backed enumeration, so it becomes this

enum MaritalStatus: string {
  case Single = 'Single';
  case Married = 'Married/Civil Partner';
  case Divorced = 'Divorced/Civil Partnership Dissolved';
  case Separated = 'Separated';
  case Widowed = 'Widowed/Surviving Civil Partner';
}

You still can’t do

echo $employeeMaritalStatus;

But you can now do

echo $employeeMaritalStatus->name;

which will get you “Married”, or

echo $employeeMaritalStatus->value;

which gets you “Married/Civil Partner”;

The next thing you might want to do is convert a string to an enum value. Say if an API has returned a string value “Married”, you want to be able to convert that to a proper enum in your PHP object.

So we add a couple of static methods

enum MaritalStatus: string {
  case Single = 'Single';
  case Married = 'Married/Civil Partner';
  case Divorced = 'Divorced/Civil Partnership Dissolved';
  case Separated = 'Separated';
  case Widowed = 'Widowed/Surviving Civil Partner';

  public static function fromString(string $name): MaritalStatus {
    try {
      return self::{$name};
    } catch (\Error) {
      throw new \ValueError('"'.$name.'" is not a valid value for '.self::class);
    }
  }

  public static function fromNullableString(?string $name): ?MaritalStatus {
    return $name === null ? null : self::fromString($name);
  }
}

So now you can do

$myString = 'Married';
$employeeMaritalStatus = MaritalStatus::fromString($myString);

The next problem we need to solve is a problem I ran into when serializing objects containing the enum.

Say I've got a variable called $employee that contains a property $maritalStatus that I want to pass into an API

I do

$json = json_encode($employee);

to convert it to JSON to send to the API. If the marital status is “Single” or “Separated” it works, but if I send a “Married” one it falls over. The API complains that that’s not a valid MaritalStatus.

What’s happening is that by default, when you do json_encode on a backed enum, it converts it to the string value, not the enum value. So for a Single one, the API is receiving this

{
  "employeeId": 2645,
  "forename": "Jane",
  "surname": "Jones",
  "maritalStatus": "Single"
}

That’s fine because for a Single one, the enum and its string equivalent are identical, but for a Married one we’re sending

{
  "employeeId": 2645,
  "forename": "Jane",
  "surname": "Jones",
  "maritalStatus": "Married/Civil Partner"
}

The API doesn’t recognise “Married/Civil Partner” as a valid status.

So we have to control the serialisation behaviour ourselves. You implement the JsonSerializable interface.

enum MaritalStatus: string implements \JsonSerializable {
  case Single = 'Single';
  case Married = 'Married/Civil Partner';
  case Divorced = 'Divorced/Civil Partnership Dissolved';
  case Separated = 'Separated';
  case Widowed = 'Widowed/Surviving Civil Partner';

  public static function fromString(string $name): MaritalStatus {
    try {
      return self::{$name};
    } catch (\Error) {
      throw new \ValueError('"'.$name.'" is not a valid value for '.self::class);
    }
  }

  public static function fromNullableString(?string $name): ?MaritalStatus {
    return $name === null ? null : self::fromString($name);
  }

  public function jsonSerialize(): string {
    return $this->name;
  }
}

So now a Married one gets converted to JSON as “Married” instead of “Married/Civil Partner”. The API receives this

{
  "employeeId": 2645,
  "forename": "Jane",
  "surname": "Jones"
  "maritalStatus": "Married"
}

and it’s all happy.

Then to take it a step further. The fromString() and fromNullableString() both return a value of MaritalStatus, i.e. of the type that we’re currently in. Where that’s the case, you can have a return type of self, i.e.

enum MaritalStatus: string implements \JsonSerializable {
  case Single = 'Single';
  case Married = 'Married/Civil Partner';
  case Divorced = 'Divorced/Civil Partnership Dissolved';
  case Separated = 'Separated';
  case Widowed = 'Widowed/Surviving Civil Partner';

  public static function fromString(string $name): self {
    try {
      return self::{$name};
    } catch (\Error) {
      throw new \ValueError('"'.$name.'" is not a valid value for '.self::class);
    }
  }

  public static function fromNullableString(?string $name): ?self {
    return $name === null ? null : self::fromString($name);
  }

  public function jsonSerialize(): string {
    return $this->name;
  }
}

So now those three methods don’t have anything in them that refers to a specific enum type. They will work for any enum type. So you’d think that’s an obvious candidate for an abstract base class, but you can’t do inheritance on enums.

So there’s a thing called a Trait in PHP which I’d heard of but never actually looked into. It’s a bit like a quick and dirty base class. Or like one of those classes that’s got nothing but static methods, except the methods don’t have to be static.

trait Multiplying {
  public function multiplyBy2() {
    return $this->myVal * 2;
  }

  public function multiplyBy4() {
    return $this->myVal * 4;
  }
}

So once you’ve defined it, any class that uses that trait gets those methods.

class MyClass {
  use Multiplying;

  public int $myVal;
}

$myObject = new MyClass();
$myObject->myVal = 5;

echo $myObject->multiplyBy2();
echo '<br>';
echo $myObject->multiplyBy4();

That’s a rubbish example, but you get the idea.

So if we define a trait like this

trait CommonEnumMethods {
  public static function fromString(string $name): self {
    try {
      return self::{$name};
    } catch (\Error $e) {
      throw new \ValueError('"'.$name.'" is not a valid value for '.self::class);
    }
  }

  public static function fromNullableString(?string $name): ?self {
    return $name === null ? null : self::fromString($name);
  }

  public function jsonSerialize(): string {
    return $this->name;
  }
}

Our actual enum can look like this

enum MaritalStatus: string implements \JsonSerializable {
  use CommonEnumMethods;

  case Single = 'Single';
  case Married = 'Married/Civil Partner';
  case Divorced = 'Divorced/Civil Partnership Dissolved';
  case Separated = 'Separated';
  case Widowed = 'Widowed/Surviving Civil Partner';
}

And it gets all the methods from the trait. So now all new enums that we add can just use the trait to get all the functionality that we need.

If you've never used EF Core before you need to install the tools globally.

Open the Visual Studio Terminal window and do

dotnet tool install --global dotnet-ef

If you've already installed the tools but there has been an update in the meantime, you can bring them up to date by doing

dotnet tool update --global dotnet-ef

Your project needs a couple of NuGet packages

• Microsoft.EntityFrameworkCore.Design
• Microsoft.EntityFrameworkCore.Sqlite

(If you're using a different database then replace the SQLite package.)

You start off by defining some entity classes, e.g.

public class Movie {
  public int Id { get; set; }
  public required string Title { get; set; }
  public int? ReleaseYear { get; set; }
}

Create a new class that inherits from DbContext

public class MovieDatabaseDbContext : DbContext {
  public MovieDatabaseDbContext(DbContextOptions options) : base(options) { }
  public DbSet<Movie> Movies => Set<Movie>();
}

Register it in Program.cs

builder.Services.AddDbContext(options =>
  options.UseSqlite(builder.Configuration.GetConnectionString("Default")));

And add the connection string into appsettings.json

"ConnectionStrings": { "Default": "Data Source=movies.db" }

Now we're going to create a migration. That word has always bamboozled me because to me, a migration is a big project where you're changing something important, like moving your application to a different framework or a different database. But in the context of EF Core, a migration is a set of instructions for creating or updating your database schema.

Open the Visual Studio Terminal window, navigate to the folder that contains the project that contains your DbContext class, and do

dotnet ef migrations add InitialCreate

InitialCreate here can be anything you like. It's just a name that uniquely identifies this migration.

EF Core builds your project, and creates an instance of your DbContext class so that it can figure out what it needs to do to create the database.

If your DbContext isn't in an ASP.NET project (for example if you're putting your data access code in a separate class library), you need a slightly different command

dotnet ef migrations add InitialCreate --project MyDataAccessLib --startup-project MyWebApiProject

--project tells it where to look for the DbContext class

--startup-project tells it where to look for the code that instantiates the DbContext (in the Program.cs of your API project)

You can leave out --project and it'll look in the project folder that you're currently in.

If that completes successfully, you'll have a Migrations folder containing

• [timestamp]_InitialCreate.cs
• [timestamp]_InitialCreate.Designer.cs
• MovieDatabaseDbContextModelSnapshot.cs

InitialCreate.cs is the migration code. It contains a method Up() to implement the changes in this migration, and a method Down() to reverse them.

You don't have to worry about InitialCreate.Designer.cs. That's just internal stuff that EF Core needs.

The snapshot is a snapshot of where the database should be when all the migrations have been applied.

To actually create the database, in the Terminal window, run

dotnet ef database update

This will create the database (movies.db) in the same folder as your project.