README

POPO - "Plain Old Php Object" was inspired by "Plain Old Java Object" (POJO) concept.

POPO generator can also locate, load, validate, and combine schemas to create PHP source code files, representing Arrays / Data Structures / Data Transfer Objects / Doctrine ORM Entities / MongoDB ODM Documents.

POPO Schema can be defined and extended on few levels, and it can be defined in multiple files.

Examples

Single schema file

Simple schema in YAML format, describing properties and relations of POPO objects.

#example.popo.yml
$:
  config:
    namespace: App\Example\Readme
    outputPath: tests/

Example:
  Foo:
    property: [
      {name: title}
      {name: bar, type: popo, default: Bar::class}
    ]

  Bar:
    property: [
      {name: title}
    ]

Multiple schema files

The same example can be split into multiple files. However, this time, it's the Bar that modifies the Foo definition.

#foo.popo.yml
Example:
  Foo:
    property: [
      {name: title}
    ]

#bar.popo.yml
Example:
  Foo:
    property: [
      {name: bar, type: popo, default: Bar::class}
    ]

  Bar:
    property: [
      {name: title}
    ]

The generated code is the same, but the schema dependencies are inverted.

In both cases, Foo object uses Bar object as its dependency, and they are both defined under Example schema name.

Generated code usage examples

Instantiate data structure from an array.

use App\Example\Readme\Foo;

$data = [
    'title' => 'A title',
    'bar' => [
        'title' => 'Bar lorem ipsum',
    ],
];

$foo = (new Foo)->fromArray($data);

echo $foo->getTitle();
echo $foo->requireBar()->getTitle();

Output:

A title
Bar lorem ipsum

Display hierarchy of objects as an array.

use App\Example\Readme\Foo;

$foo = (new Foo);
$foo->requireBar()->setTitle('new value');

print_r($foo->toArray());

Output:

[
    'title' => null,
    'bar' => [
        'title' => 'new value',
    ],
];

Run bin/popo generate -s tests/fixtures/popo-readme.yml or docker-popo generate -s tests/fixtures/popo-readme.yml to generate files from this example.

Installation

composer require popo/generator --dev

Note: The installation can be skipped when using docker, see Docker support section.

Usage

You can either use it as composer dependency or as docker command.

Define schema file, see tests/fixtures for examples.

Generate POPO files, run:

with composer

vendor/bin/popo generate -s <schema-path> -o <output-path>

with docker

docker-popo generate -s <schema-path> -o <output-path>

For example: bin/popo generate -s tests/fixtures/popo.yml or docker-popo generate -s tests/fixtures/popo.yml.

POPO Schema

POPO Schema can be defined and extended on few levels- and it can be defined in multiple files.

The schema supports key mapping- inheritance- collections and encapsulation of other POPO objects.

Schema Definition

$: # file-config, shared configuration for all POPO objects in current schema file
  config:
    namespace: string
    outputPath: string
    namespaceRoot: string|null # if set remaps namespace and outputPath
    extend: string|null # which class POPO objects should extend from
    implement: string|null # which interface POPO objects should implement
    comment: string|null # Class docblock comment
    phpComment: string|null # Generated PHP File docblock comment
    use: array<string>|[] # Import block in generated PHP class
    trait: array<string>|[] # Traits to be used with generated class
    attribute: string|null # Class attributes as string
    attributes: array<key, value>|[] # Class attributes as key value pairs
    classPluginCollection: array<string>|[]
    phpFilePluginCollection: array<string>|[]
    namespacePluginCollection: array<string>|[]
    propertyPluginCollection: array<string>|[]
    mappingPolicyPluginCollection: array<string>|[]
  default: array # default values
  property: array # shared properties

SchemaName: # schema-config
  $: # shared configuration for all POPO objects in SchemaName, in all schema files
    config:
      namespace: string
      outputPath: string
      namespaceRoot: string|null
      extend: string|null
      implement: string|null
      comment: string|null
      phpComment: string|null
      use: array<string>|[]
      trait: array<string>|[]
      attribute: string|null,
      attributes: array<key, value>|[]
      classPluginCollection: array<string>|[]
      phpFilePluginCollection: array<string>|[]
      namespacePluginCollection: array<string>|[]
      propertyPluginCollection: array<string>|[]
      mappingPolicyPluginCollection: array<string>|[]
    default: array
    property: [{
      name: string,
      type:
        type: string
        default: string
        supportedTypes: ['array','bool','float','int','string','mixed','const','popo', 'datetime'],
      comment: string|null,
      default: mixed,
      itemType: string|null,
      itemName: string|null,
      extra: {timezone: ..., format: ...},
      attribute: string|null,
      attributes: array<key, value>|[]
      mappingPolicy: ['none', 'lower', 'upper', 'camel-to-snake', 'snake-to-camel'],
      mappingPolicyValue: string|null
    }]

  PopoName: # popo-config
    config:
      namespace: string
      outputPath: string
      namespaceRoot: string|null
      extend: string|null
      implement: string|null
      comment: string|null
      phpComment: string|null
      use: array<string>|[]
      trait: array<string>|[]
      attribute: string|null,
      attributes: array<key, value>|[]
      classPluginCollection: array<string>|[]
      phpFilePluginCollection: array<string>|[]
      namespacePluginCollection: array<string>|[]
      propertyPluginCollection: array<string>|[]
      mappingPolicyPluginCollection: array<string>|[]
    default: array
    property: [{
      name: string,
      type:
        type: string
        default: string
        supportedTypes: ['array','bool','float','int','string','mixed','const','popo', 'datetime'],
      comment: string|null,
      default: mixed,
      itemType: string|null,
      itemName: string|null,
      extra: {timezone: ..., format: ...},
      attribute: string|null,
      attributes: array<key, value>|[]
      mappingPolicy: ['none', 'lower', 'upper', 'camel-to-snake', 'snake-to-camel'],
      mappingPolicyValue: string|null
    }]

Schema configuration options

`namespace`

Defines generated class namespace.

config:
  namespace: App\Example
  ...

`outputPath`

Defines output directory.

config:
  outputPath: src/
  ...

`namespaceRoot`

Defines the begging of outputPath that should be removed. For example to generated files under src/Example with App\Example namespace.

config:
  namespace: App\Example
  outputPath: src/
  namespaceRoot: App\
  ...

`extend`

Which class should the generated class extend from. Must start with \ or contain ::class.

config:
  extend: \App\Example\AbstractDto::class
  ...

`implement`

Which interface should the generated class implement. Must start with \ or contain ::class.

config:
  implement: \App\Example\DtoInterface::class
   ...

`comment`

Class comment.

config:
  comment: |
    @Document(collection="events")
...

`phpComment`

Generated PHP file comment.

config:
  phpComment: |
    Auto generated.
    @SuppressWarnings(PHPMD)
    @phpcs:ignoreFile
...

`use`

Import statements.

  config:
    use:
      - Doctrine\ODM\MongoDB\Mapping\Annotations\Document
      - Doctrine\ODM\MongoDB\Mapping\Annotations\Field
      - Doctrine\ODM\MongoDB\Mapping\Annotations\Id
    ...

`trait`

Traits statements.

  config:
    trait:
      - App\Example\MyTrait
    ...

`attribute`

Class attributes value.

  config:
    attribute: |
      #[Doctrine\ORM\Mapping\Entity(repositoryClass: LogEventRepository::class)]
    ...

`attributes`: `array`

Attribute value as collection. Supported values:

name
value: mixed

  config:
    attributes:
      - name: Doctrine\ORM\Mapping\Entity
        value: {repositoryClass: LogEventRepository::class}
    ...

`classPluginCollection`: `array`

Additional plugins used to generate methods.

  config:
    classPluginCollection:
      - \App\Plugin\ExampleMethodPopoPlugin::class
    ...

`namespacePluginCollection`: `array`

Additional plugins used to generate namespace block.

  config:
    namespacePluginCollection:
      - \App\Plugin\ExampleNamespacePopoPlugin::class
    ...

`propertyPluginCollection`: `array`

Additional plugins used to generate properties.

  config:
    propertyPluginCollection:
      - \App\Plugin\ExamplePropertyPopoPlugin::class
    ...

`mappingPolicyPluginCollection`: `array`

Set of plugins used to map property names, e.g. fooId => FOO_ID.

  config:
    mappingPolicyPluginCollection:
      - \App\Plugin\SpecialCaseMappingPopoPlugin::class
    ...

Property configuration options

`name`

The name of the property. The property related methods will be generated based on this value. For example getFooBar(). This is required parameter.

property: 
  - name: title
    ...

`type`

Property data type, supported are:

array
bool
float
int
string
mixed
const
popo
datetime

Default property type is string.

property: 
  - name: precision
    type: float
    ...

`comment`

Docblock value for property and methods.

property: 
  - name: title
    comment: Lorem ipsum
    ...

`default: mixed`

Default value.

property: 
  - name: items
    default: \App\ExampleInterface::TEST_BUZZ
    ...

`extra: array`

Used by datetime data type. Supported values:

format
timezone

property: 
    - name: created
      type: datetime
      extra: 
          timezone: Europe/Paris
          format: D, d M y H:i:s O
    ...

`itemType`

Used by array data type together with itemName element. Describes type of single array element.

property:
    - name: products
      type: array
      itemType: Product::class
    ...

`itemName`

Used by array data type. Describes name of single array element. For example: setProducts(array $products), addProduct(Product $item).

property:
    - name: products
      type: array
      itemName: product
    ...

`attribute`

Attribute value.

property:
    - name: price
      attribute: |
      #[Doctrine\ORM\Mapping\Column(type: Types::INTEGER)]
    ...

`attributes`: `array`

Attribute value as collection. Supported values:

name
value: mixed

property:
    - name: id
      attributes:
        - name: Doctrine\ORM\Mapping\Column
          value: ['length: 255']
    ...

`mappingPolicy: array`

Dynamically remaps property names, for example, fooId => FOO_ID. Supported values:

none
lower
upper
camel-to-snake
snake-to-camel

property:
  - name: fooId
    mappingPolicy:
      - camel-to-snake
      - upper
    ...

`mappingPolicyValue`

Statically remaps property names, for example, fooId => FOO_ID.

property:
  - name: fooId
    mappingPolicyValue: FOO_ID
  ...

Schema Inheritance

The popo-config values override schema-file-config values- and schema-file-config values overwrite schema-config values.

On top of that there is a global-config that is defined when using --schemaConfigFilename parameter.

`schema-config`

The configuration was defined as a Schema property. It will be used by all POPO objects in all files under given schema.

`schema-file-config`

The configuration was defined as a SchemaFile property. It will be used by all POPO objects in current file.

`popo-config`

The configuration was defined as a POPO property. It will be used by one specific POPO objects in current file.

See tests/fixtures for schema examples.

Property name remapping

POPO can remap property keys names, for example change foo_id into fooId.

See Property Name Remapping doc.

Pluggable architecture

New functionality can be provided on the command line, or via configuration.

See Plugins doc.

Doctrine Support

See Doctrine Support doc.

Command line options

See Command Line Options doc.

More Examples

See fixtures and tests for more usage examples.

Composer script

Add popo scrip to composer and run composer popo in a project.

    "scripts": {
        "popo": [
            "bin/popo generate -s <schema-path>"
        ]
    },
    "scripts-descriptions": {
        "popo": "Generate POPO files"
    }

Docker support

With docker you can generate files without installing POPO as dependency in the project.

docker container run -it --rm oliwierptak/popo /app/bin/popo

You can either run the command directly, or create an alias, e.g.:

alias docker-popo='docker container run -it --rm oliwierptak/popo /app/bin/popo ${@}'

For example:

docker-popo generate -s tests/fixtures/popo.yml
docker-popo report -s tests/fixtures/popo.yml

PHP version compatibility

POPO v1.x - PHP 7.2+
POPO v2.x - PHP 7.2+
POPO v3.x - PHP 7.4+
POPO v4.x - PHP 7.4+
POPO v5.x - PHP 7.4+
POPO v6.x - PHP 8+

POPO schema example

Schema example that produces generated PopoConfigurator class.

$:
  config:
    namespace: Popo
    outputPath: src/
    phpComment: |
      @SuppressWarnings(PHPMD)
      @phpcs:ignoreFile

Popo:
  PopoConfigurator:
    default:
      phpFilePluginCollection:
        - \Popo\Plugin\PhpFilePlugin\StrictTypesPhpFilePlugin::class
        - \Popo\Plugin\PhpFilePlugin\CommentPhpFilePlugin::class
      namespacePluginCollection:
        - \Popo\Plugin\NamespacePlugin\UseStatementPlugin::class
      classPluginCollection:
        - \Popo\Plugin\ClassPlugin\ClassAttributePlugin::class
        - \Popo\Plugin\ClassPlugin\ClassCommentPlugin::class
        - \Popo\Plugin\ClassPlugin\ConstPropertyClassPlugin::class
        - \Popo\Plugin\ClassPlugin\DateTimeMethodClassPlugin::class
        - \Popo\Plugin\ClassPlugin\ExtendClassPlugin::class
        - \Popo\Plugin\ClassPlugin\ImplementClassPlugin::class
        - \Popo\Plugin\ClassPlugin\IsNewClassPlugin::class
        - \Popo\Plugin\ClassPlugin\ListModifiedPropertiesClassPlugin::class
        - \Popo\Plugin\ClassPlugin\MetadataClassPlugin::class
        - \Popo\Plugin\ClassPlugin\ModifiedToArrayClassPlugin::class
        - \Popo\Plugin\ClassPlugin\PopoMethodClassPlugin::class
        - \Popo\Plugin\ClassPlugin\RequireAllClassPlugin::class
        - \Popo\Plugin\ClassPlugin\UpdateMapClassPlugin::class
        - \Popo\Plugin\ClassPlugin\FromArrayClassPlugin::class
        - \Popo\Plugin\ClassPlugin\FromMappedArrayClassPlugin::class
        - \Popo\Plugin\ClassPlugin\ToArrayClassPlugin::class
        - \Popo\Plugin\ClassPlugin\ToMappedArrayClassPlugin::class
        - \Popo\Plugin\ClassPlugin\MappingPolicyMethod\ToArrayLowercasePlugin::class
        - \Popo\Plugin\ClassPlugin\MappingPolicyMethod\ToArrayUppercasePlugin::class
        - \Popo\Plugin\ClassPlugin\MappingPolicyMethod\ToArraySnakeToCamelPlugin::class
        - \Popo\Plugin\ClassPlugin\MappingPolicyMethod\ToArrayCamelToSnakePlugin::class
      propertyPluginCollection:
        - \Popo\Plugin\PropertyPlugin\AddItemPropertyMethodPlugin::class
        - \Popo\Plugin\PropertyPlugin\DefinePropertyPlugin::class
        - \Popo\Plugin\PropertyPlugin\GetPropertyMethodPlugin::class
        - \Popo\Plugin\PropertyPlugin\HasPropertyMethodPlugin::class
        - \Popo\Plugin\PropertyPlugin\RequirePropertyMethodPlugin::class
        - \Popo\Plugin\PropertyPlugin\SetPropertyMethodPlugin::class
      mappingPolicyPluginCollection:
        none: \Popo\Plugin\MappingPolicy\NoneMappingPolicyPlugin::class
        lower: \Popo\Plugin\MappingPolicy\LowerMappingPolicyPlugin::class
        upper: \Popo\Plugin\MappingPolicy\UpperMappingPolicyPlugin::class
        snake-to-camel: \Popo\Plugin\MappingPolicy\SnakeToCamelMappingPolicyPlugin::class
        camel-to-snake: \Popo\Plugin\MappingPolicy\CamelToSnakeMappingPolicyPlugin::class
    property: [
      {name: schemaPath}
      {name: namespace}
      {name: namespaceRoot}
      {name: outputPath}
      {name: phpFilePluginCollection, type: array, itemType: string, itemName: phpFilePluginClass}
      {name: namespacePluginCollection, type: array, itemType: string, itemName: namespacePluginClass}
      {name: classPluginCollection, type: array, itemType: string, itemName: classPluginClass}
      {name: propertyPluginCollection, type: array, itemType: string, itemName: propertyPluginClass}
      {name: mappingPolicyPluginCollection, type: array, itemType: string, itemName: mappingPolicyPluginClass}
      {name: schemaConfigFilename}
      {name: schemaPathFilter}
      {name: schemaFilenameMask, default: '*.popo.yml'}
      {name: shouldIgnoreNonExistingSchemaFolder, type: bool}
    ]}}

popo / generator

Maintainers

Details

README

Examples

Single schema file

Multiple schema files

Generated code usage examples

Instantiate data structure from an array.

Display hierarchy of objects as an array.

Installation

Usage

POPO Schema

Schema Definition

Schema configuration options

namespace

outputPath

namespaceRoot

extend

implement

comment

phpComment

use

trait

attribute

attributes: array

classPluginCollection: array

namespacePluginCollection: array

propertyPluginCollection: array

mappingPolicyPluginCollection: array

Property configuration options

name

type

comment

default: mixed

extra: array

itemType

itemName

attribute

attributes: array

mappingPolicy: array

mappingPolicyValue

Schema Inheritance

schema-config

schema-file-config

popo-config

Property name remapping

Pluggable architecture

Doctrine Support

Command line options

More Examples

Composer script

Docker support

PHP version compatibility

POPO schema example

`namespace`

`outputPath`

`namespaceRoot`

`extend`

`implement`

`comment`

`phpComment`

`use`

`trait`

`attribute`

`attributes`: `array`

`classPluginCollection`: `array`

`namespacePluginCollection`: `array`

`propertyPluginCollection`: `array`

`mappingPolicyPluginCollection`: `array`

`name`

`type`

`comment`

`default: mixed`

`extra: array`

`itemType`

`itemName`

`attribute`

`attributes`: `array`

`mappingPolicy: array`

`mappingPolicyValue`

`schema-config`

`schema-file-config`

`popo-config`