PHPackages                             represent/represent - 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. represent/represent

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

represent/represent
===================

Tools that can build differient representations of objects

043PHP

Since Jan 6Pushed 11y ago1 watchersCompare

[ Source](https://github.com/MarcusFulbright/represent)[ Packagist](https://packagist.org/packages/represent/represent)[ RSS](/packages/represent-represent/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Introduction
============

[](#introduction)

Represent provides a serialization layer that can create and configure different representations of resources. When implementing a web service, having dedicated layer of that service control the representation of resources will provide a high degree of flexibility. In the context of a RESTful web service, REST embodies a set of design constraints. Two concepts lie underneath the technologies that have evolved from the design constraints of REST. Resources, and Representations.

- Resources: Data models usually compose the resources offered by a web service. In a broader sense, a resource is anything important enough to be referred to as a thing in and of itself. For a RESTful web service, URI's describe resources. GET /car/1 described a car resource.
- Representations: A representation is any machine readable document that contains any information about a resource. For RESTful services, a representation should also explain the current state of the resource.

Creating different representations of resources can be as simple as letting a client decide what format it would like to receive. Or it can get more complicated, such as controlling what properties of a resource should get included in a response. Represent packages all of this functionality together.

Serializers and Builders
========================

[](#serializers-and-builders)

Your application should interact with Represent's serializers. Currently, a GenericSerializer and a HalSerializer exist. These classes handle preparing a specific representation of a given object and returning the data in a serialized format (currently JSON only). These serializers use builders to construct the desired representation. The most important Builder is the GenericRepresentation Builder. This is the entry point for all representations. The GenericBuilder handles parsing out the configuration for a class (currently given in annotations) and creates a representation composed of stdClass objects, arrays, and primitive type values. Format specific builders, such as the HalBuilder, take a Generic Representation and modify it comply with a specific format's standards. In the case of Hal, handling \_links and \_embedded. You can interact with the builders directly, however, only interacting with the serializers can reduce complexity in your application and help keep the representation layer separated.

Generic Configuration
=====================

[](#generic-configuration)

Configuration that always gets used to create a Generic Representation. All of these options will work with any specific format builder. Currently, Represent only supports class configuration with annotations. All examples will show annotations.

Class Level
-----------

[](#class-level)

The following annotations function at the class level:

### Exclusion Policy

[](#exclusion-policy)

This gets set at the class level and can either be `whiteList` or `blackList`. This tells The GenericRepresentationBuilder what properties to either include or exclude.

- `whiteList`: all properties included by default unless they are marked `hidden`
- `blackList`: all properties excluded by default unless they are marked with `show`

NOTE: if an exclusion policy is not specified, `whiteList` is used by default

Example:

```
use Represent\Annotations as Represent;

/**
 * @Represent\ExclusionPolicy(policy="whiteList")
 */
class Car
```

Property Level
--------------

[](#property-level)

The following annotations function at the property level:

### Hide

[](#hide)

Only used when a class's exclusion policy is set to `whiteList`. Can be used to hide a property from all representations.

Example (excludes vinNumber):

```
use Represent\Annotations as Represent;

/**
 * @Represent\ExclusionPolicy(policy="whiteList")
 */
 class Car
 {
     public $make;

     public $model;

     public $dateBuilt;

     /**
      * @Represent\Hide()
      */
     private $vinNumber;
 }
```

### Show

[](#show)

Only used when a class's exclusion policy is set to `blackList`. Can be used to show properties in representations.

Example (shows make and model):

```
use Represent\Annotations as Represent

 /**
  * @Represent\ExclusionPolicy(policy="blackList")
  */
 class Car
 {
     /**
      * @Represent\Show()
      */
     public $make;

     /**
      * @Represent\Show()
      */
     public $model;

     public $dateBuilt;

     private $vinNumber;
 }
```

### Property

[](#property)

Used to control the serialized name and data type of the value.

Example (renames `dateBuilt` to `year` and forces it to integer:

```
use Represent\Annotations as Represent

class Car
{
   public $make;

   public $model;

   /**
    * @Represent\Property(name="year", type="integer")
    */
   public $dateBuilt;

   private $vinNumber
}
```

### View

[](#view)

Used to control specific views of resources. A view of a resource is like a particular context that can get represented. Anything excluded via the exclusion policy will get excluded. Properties that do not have a view will always show up, if the exclusion policy allows. Properties with a view will only show up when that view is represented.

Example (the `vinNumber` will only represented in the `owner` view):

```
use Represent\Annotations as Represent

class Car
{
    public $make;

    public $model;

    public $dateBuilt;

    /**
     * @Represent\View(name={"owner"})
     */
    private $vinNumber;
}
```

Hal Configuration
=================

[](#hal-configuration)

The following configuration options only work with the Hal Builder and configure options specific to the Hal Format (\_links and \_embedded).

Class Level
-----------

[](#class-level-1)

The following annotations function at the class level:

### Link & LinkCollection

[](#link--linkcollection)

LinkCollection the container for all of the Links that should be included in `_links`. Currently links are all generated using the SymfonyUrlGenerator. The links `uri` property takes a route name. Parameters can be defined with expressions using The Expression Language

Example yields the following json:

```
use Represent\Annotations as Represent;

/**
 * @Represent\LinkCollection(links={
 *    @Represent\Link(
 *         name="self",
 *         uri="get_car_by_ID",
 *         parameters={"id" = "expr('object->id')" }
 *     )
 * })
 */
class Car
{
    public $id;

    public $make;

    public $model;
}
```

```
{
  "id":1,
  "make":"dodge",
  "model":"neon",
  "_links":{
    "self":{
      "href":"www.mysite.com/car/1"
    }
  }
}
```

Property Level
--------------

[](#property-level-1)

The following annotations function at the property level:

### Embedded

[](#embedded)

Causes properties to show up in `_embedded` and NOT as properties on the object itself.

Example yields the following json:

```
use Represent\Annotations as Represent

class Car
{
    /*
     * @Represent\Embedded()
     */
    public $type

    public $dateBuilt;
}

class Type
{
    public $make;

    public $model;
}
```

```
{
    "dateBuilt":"1989",
    "_embedded":{
        "type": {
            "make":"Dodge",
            "model":"Neon"
        }
    }
}
```

Full Annotation Reference
=========================

[](#full-annotation-reference)

#### @ExclusionPolicy

[](#exclusionpolicy)

```
use Represent\Annotations as Represent;

/**
 * @Represent\ExclusionPolicy(policy="whiteList")
 */
class Car
```

PropertyRequiredContentpolicyYes('whiteList' or 'blackList')#### @Hide

[](#hide-1)

```
use Represent\Annotations as Represent;

/**
 * @Represent\ExclusionPolicy(policy="whiteList")
 */
 class Car
 {
     /**
      * @Represent\Hide()
      */
     private $vinNumber;
 }
```

PropertyRequiredContentn/an/an/a#### @Show

[](#show-1)

```
use Represent\Annotations as Represent

 /**
  * @Represent\ExclusionPolicy(policy="blackList")
  */
 class Car
 {
     /**
      * @Represent\Show()
      */
     public $make;
 }
```

PropertyRequiredContentn/an/an/a#### @Property

[](#property-1)

```
use Represent\Annotations as Represent

class Car
{
   public $make;

   public $model;

   /**
    * @Represent\Property(name="year", type="integer")
    */
   public $dateBuilt;

   private $vinNumber
}
```

PropertyRequiredContentNameNostringTypeNostring (integer or string or boolean or datetime)#### @View

[](#view-1)

```
use Represent\Annotations as Represent

class Car
{
    public $make;

    public $model;

    public $dateBuilt;

    /**
     * @Represent\View(name={"owner"})
     */
    private $vinNumber;
}
```

PropertyRequiredContentnameYesarray (strings)#### @LinkCollection && @Link

[](#linkcollection--link)

```
use Represent\Annotations as Represent;

/**
 * @Represent\LinkCollection(links={
 *    @Represent\Link(
 *         name="self",
 *         uri="get_car_by_ID",
 *         parameters={"id" = "expr('object->id')" }
 *     )
 * })
 */
class Car
{
    public $id;

    public $make;

    public $model;
}
```

**@LinkCollection**

PropertyRequiredContentlinksYesArray (Link)**@Link**

PropertyRequiredContentnameyesstringuriyesstringparametersnoarray (key,value)viewsnoarray (string)absolutenoboolean#### @Embedded

[](#embedded-1)

```
use Represent\Annotations as Represent

class Car
{
    /*
     * @Represent\Embedded()
     */
    public $type

    public $dateBuilt;
}
```

PropertyRequiredContentn/an/an/a

###  Health Score

21

—

LowBetter than 18% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity8

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity41

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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a4726039ba45ca6ddf268f7ab44c9a197c97950ecc6e084786f1d586fccd8ef?d=identicon)[MarcusFulbright](/maintainers/MarcusFulbright)

---

Top Contributors

[![MarcusFulbright](https://avatars.githubusercontent.com/u/2130243?v=4)](https://github.com/MarcusFulbright "MarcusFulbright (2 commits)")

### Embed Badge

![Health badge](/badges/represent-represent/health.svg)

```
[![Health](https://phpackages.com/badges/represent-represent/health.svg)](https://phpackages.com/packages/represent-represent)
```

###  Alternatives

[sof3/await-generator

Use async/await in PHP using generators

12522.6k19](/packages/sof3-await-generator)[llm-agents/agents

LLM Agents PHP SDK - Autonomous Language Model Agents for PHP

16410.9k9](/packages/llm-agents-agents)

PHPackages © 2026

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