Download the PHP package maer/entity without Composer

Create predefined entity objects

This version contains breaking changes and aren't compatible with version 1.x

Instead of passing around entities as arrays or instances of StdClass, where you never can trust if a specific key or property exists, or that they contain the correct datatype, it's better to use predefined entity objects.

I created this class when I was building a REST-api where I had data from different sources. MySQL, for example, defaults to returning all values as strings.

There are other situations where one parameter from the data source might have changed name, or been removed. Then it's nice if you don't need to go through all your code and change it where ever it's being used.

Install

Clone this repository or use composer to download the library with the following command:

Usage

• Define an entity
  • Default property values and types
  • Protect properties
  • Remap properties
  • Remap nested properties
• Instantiate an entity
  • Create a default entity
  • Convert an array to entity
  • Convert a multidimensional array to a list of entities
  • Get an array instead of collection
  • Modify values on instantiation
  • Change the behavior with the $_setup property
• Helper methods
  • Check if a property exists
  • Convert an entity to arrays
  • Convert an entity to JSON
  • Replace entity data
  • Reset an entity
  • Reset a property
  • Create your own helpers
• Collections
  • Count
  • Get the first entity
  • Get the last entity
  • Get a list of property values
  • Sort the entities
  • Remove an entity
• Add-ons
  • DateTimeTrait
    • date()
    • dateTime()
    • timestamp()
  • TextTrait
    • excerpt()
• Changes in version 2

Define an entity

When defining an entity, you start create a new class which extends Maer\Entity\Entity:

Default property values and types

Creating an empty entity isn't that exiting. We should define some properties and default values:

When you define a default value, it's important that you set the default values to the correct data type. Later on when you're setting/updating a property value, the new value will be cast to the same data type as the default. The data types that are supported for automatic casting are: integers, strings, booleans and floats/doubles. If the default value is null, it can be set to anything.

Protect properties

If you want to be able to use a property in your code, but don't want to expose it in, say, an API response, you can "protect" it. An example would be a user entity having a password hash. To protect (remove) a property on JSON serialization or when fetching it as an array, you can protect using the protect()-method like this:

Remap properties

Sometimes the source array might have different key names than the defined entity params. To make it as easy as possible for you, you can map param names and your entity will automatically remap them upon instantiation.

If you now send in an array with a email key, the value will be mapped as username.

Remap nested properties

If you want to map a value in a multidimensional array, you can do just as above, but using dot notation as map key.

This will map ['user' => ['username' => 'Chuck Norris']] as just username. There is no limit on how many nested levels you can go.

Instantiate an entity

You can instantiate an entity in several ways, depending on your needs.

Create a default entity

Since it's a class, you can create a new entity with the default values like this:

You can also set new values for it by passing an array to the constructor:

Just remember that the values will be cast to the same datatype as the default value.

Convert an array to entity

When creating just one entity, you can use the above constructor method, or you can use the static Entity::make() method:

Convert a multidimensional array to a list of entities

The static Entity::make() method is a bit more clever and can do more than just give you one entity. For example, if you pass a multidimensional array, it will give you a Collection-instance with entities back:

You can also define what property should be used as the array key, making it an associative array.

Get an array instead of collection

If you rather want the make()-method to return an array instead of a Collection-instance, you can pass true as the fourth argument:

Modify values on instantiation

Sometimes you get a list of values which needs to be modified before you create the entity. In this example, we will show an example of how we can prepend http:// in front of an URL, in case it is missing:

Propose that we have an entity and dataset looking like this:

Sure, we could add http:// before we instantiate the entity, but that would require us to repeat it where ever we instantiate the entity. It would also mean that we would need to manually iterate through the dataset, if it is a list of websites.

Modifier on instantiation

Luckily, we can send in a modifier in form of a closure upon entity creation:

As you can see, the closure will get the $params-array as reference, meaning that it doesn't need to return anything.

You can do the same using the static Entity::make() method:

Global modifier

Using a closure works well if you want to add a modifier for some specific instances. However, if you want to use your modifier for every instance, you can use the modified()-method instead:

Note: If you have a global modifier()-method and still send in a modifier upon instantiation, the global modifier will be called first and your instance-specific modifier last.

Helper methods

Check if a property exists

If you try to get or set a property that doesn't exist, an \InvalidArgumentException will be thrown, except from when the entity is created through the new Entity or Entity::make()-method or when you use the replace()-method.

To check if a property exists, use the has()-method:

The first argument is the name of the property holding the value, the second argument is the format (defaults to: "F j, Y").

This method also works for properties holding unix timestamps.

Convert an entity to arrays

If you need to convert an entity to array, use asArray():

All properties returned by the protect()-method will be removed.

Convert an entity to JSON

The Entity-class implements the JsonSerializable-interface, so just use json_encode():

All properties returned by the protect()-method will be removed.

Replace entity data

Sometimes you want to update the data in an entity. If it's just a few values, then doing $entity->foo = 'bar'; will work fine, but if you have larger entities with a lot of properties you want to replace, you can use the replace()-method:

This will replace the existing entity-properties with the data from the array.

You can also pass in a modifier:

Reset an entity

If you, for what ever reason, need to reset an entity to it's default values, use the reset()-method:

Reset a property

If you just want to reset a specific property to it's default value, use the resetProperty()-method:

Create your own helpers

You can of course create your own helpers:

And just access it like any other method: $hero->myNewHelper()

Collections

When you use the make()-method to create multiple entities at the same time, you will get an instance of Maer\Entity\Collection back.

This class can be used as an array (implementing the ArrayAccess and Countable interfaces).

This class has some helper methods on it's own.

Count

Get the collections entity count:

Get the first element

To get the first element in the collection, call the first()-method:

Get the last element

To get the last element in the collection, call the last()-method:

Get a list of property values

If you want to get all values (from all entities in a collection) from a single property:

You can also define what property to use as index by passing the property name as a second argument:

Sort the entities

You can sort the entities in a collection by using the usort()-method:

This method works exactly like the core function usort() (since it's using it in the background).

Remove an entity

To remove an entity from the collection, use the unset()-method:

Add-ons

In version 1, you had the helper method date() in the base entity class. Since version 2, all helper methods are traits which you need to add to your entities yourself. This is to keep the entity classes as lean as possible.

DateTimeTrait

The trait Maer\Entity\Traits\DateTimeTrait has some date-methods to make things a bit easier.

date

Get a property as a formatted date string:

dateTime

If you rather get a DateTime-instance back, use:

timestamp

If you rather get the date as a timestamp, use:

TextTrait

The trait Maer\Entity\Traits\TextTrait has some text-methods to make things a bit easier.

excerpt

If you just want to display an excerpt of some text, you can use the excerpt()-method:

The length of the returned string can be less than the max length, but never more. The method makes sure no words are cropped and that the suffix fits within the max length.

The defaults are 300 for max length and "..." as suffix.

Changes in version 2

Version 2 was completely rebuilt to use less memory and to be a bit faster. When tested creating 10.000 entities, it was just slightly faster, but the used memory was about 2-3 times less.

Quick overview of the biggest changes:

• Properties are now defined as protected class properties instead of $_params = []
• Entity::make() now returns an instance of Maer\Entity\Collection as default instead of an array
• Helper methods, like $entity->date(), has moved to traits and are no longer included in the base entity
• Settings, like map and protect, are now methods returning arrays instead of class properties

Note

If you have any questions, suggestions or issues, let me know!

Happy coding!