Adding a New Entity

This article provides step-by-step instructions on how to add a new entity to your project. Basic information about custom entities can be found in the separate article.

Let's say we need to keep an agenda of salesmen. After finishing this cookbook, the new salesman entity will not be presented on the FE in any fashion, however, you can continue with another cookbook that will show you how to display a list of salesmen using a grid in administration.

1. Create a new class Salesman and set it as an entity using Doctrine annotation

// src\Model\Salesman\Salesman.php

namespace App\Model\Salesman;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Table(name="salesmen")
 * @ORM\Entity
 */
class Salesman
{
}

2. Add salesmen attributes and set them as database columns using Doctrine annotations

Each salesman entity will have the following properties.

  • id - unique sequenced value for salesman identification
  • name - name of the salesman limited to 100 characters
  • registeredAt - registration date of the salesman
namespace App\Model\Salesman;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Table(name="salesmen")
 * @ORM\Entity
 */
class Salesman
{
+    /**
+     * @var int
+     *
+     * @ORM\Column(type="integer")
+     * @ORM\Id
+     * @ORM\GeneratedValue(strategy="IDENTITY")
+     */
+    protected $id;
+
+    /**
+     * @var string
+     *
+     * @ORM\Column(type="string", length=100)
+     */
+    protected $name;
+
+    /**
+     * @var \DateTime
+     *
+     * @ORM\Column(type="datetime")
+     */
+    protected $registeredAt;
}

3. Generate a database migration

Run a console command (in php-fpm container if you are using Docker) that will generate a database migration for you:

php phing db-migrations-generate

Note

More information about what Phing targets are and how they work can be found in Console Commands for Application Management (Phing Targets)

The command will print a filename of the database migration with content like this.

namespace App\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Shopsys\MigrationBundle\Component\Doctrine\Migrations\AbstractMigration;

class Version20190301122526 extends AbstractMigration
{
    /**
     * @param \Doctrine\DBAL\Schema\Schema $schema
     */
    public function up(Schema $schema): void
    {
        $this->sql('
            CREATE TABLE salesmen (
                id SERIAL NOT NULL,
                name VARCHAR(100) NOT NULL,
                registered_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
                PRIMARY KEY(id)
            )');
    }

    /**
     * @param \Doctrine\DBAL\Schema\Schema $schema
     */
    public function down(Schema $schema): void
    {
    }
}

Tip

We recommend you check this migration and verify that everything is set up as expected.
If the system doesn't generate the migration, the entity is probably in an incorrect namespace or has the wrong Doctrine annotation mapping.

4. Add default salesmen

Now, we add some entries into the new database table by modifying the database migration.

namespace App\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Shopsys\MigrationBundle\Component\Doctrine\Migrations\AbstractMigration;

class Version20190301122526 extends AbstractMigration
{
    /**
     * @param \Doctrine\DBAL\Schema\Schema $schema
     */
    public function up(Schema $schema): void
    {
        $this->sql('
            CREATE TABLE salesmen (
                id SERIAL NOT NULL,
                name VARCHAR(100) NOT NULL,
                registered_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
                PRIMARY KEY(id)
            )');

+        $this->sql('INSERT INTO salesmen (name, registered_at) VALUES (\'John Lennon\', \'2019-03-01 12:00:00\')');
+        $this->sql('INSERT INTO salesmen (name, registered_at) VALUES (\'Paul McCartney\', \'2018-04-19 15:25:42\')');
+        $this->sql('INSERT INTO salesmen (name, registered_at) VALUES (\'George Harrison\', \'2019-01-11 09:30:15\')');
+        $this->sql('INSERT INTO salesmen (name, registered_at) VALUES (\'Ringo Starr\', \'2016-12-12 18:42:00\')');
    }

    /**
     * @param \Doctrine\DBAL\Schema\Schema $schema
     */
    public function down(Schema $schema): void
    {
    }
}

5. Execute migrations to propagate all the changes to the database

Run a console command

php phing db-migrations

Conclusion

Now, there is a new entity in your system - Salesmen - for which exists a database table that has 4 records with salesmen. If you want to display a list of them in the administration, follow "Create basic grid" cookbook.