Get started

Install

composer require small/swoole-entity-manager-core

When Swoole 6 is used with MySQL PDO, enable coroutine hooks before the first database operation:

<?php

declare(strict_types=1);

if (class_exists(\Swoole\Runtime::class)) {
    \Swoole\Runtime::enableCoroutine(SWOOLE_HOOK_ALL);
}

Define an entity

Every entity must:

• extend AbstractEntity;
• have the #[OrmEntity] class attribute;
• declare at least one #[PrimaryKey] property;
• declare persisted properties with #[Field].

<?php

declare(strict_types=1);

namespace App\Entity;

use Small\SwooleEntityManager\Entity\AbstractEntity;
use Small\SwooleEntityManager\Entity\Attribute\Field;
use Small\SwooleEntityManager\Entity\Attribute\OrmEntity;
use Small\SwooleEntityManager\Entity\Attribute\PrimaryKey;
use Small\SwooleEntityManager\Entity\Enum\FieldValueType;

#[OrmEntity]
final class UserEntity extends AbstractEntity
{
    #[PrimaryKey]
    private ?int $id = null;

    #[Field(type: FieldValueType::string)]
    private ?string $username = null;

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getUsername(): ?string
    {
        return $this->username;
    }

    public function setUsername(string $username): self
    {
        $this->username = $username;

        return $this;
    }
}

Define a manager

A relational manager links an entity class to a database table and optionally to a named connection.

<?php

declare(strict_types=1);

namespace App\EntityManager;

use App\Entity\UserEntity;
use Small\SwooleEntityManager\EntityManager\AbstractRelationnalManager;
use Small\SwooleEntityManager\EntityManager\Attribute\Connection;
use Small\SwooleEntityManager\EntityManager\Attribute\Entity;

#[Connection(dbTableName: 'users', connectionName: 'default')]
#[Entity(UserEntity::class)]
final class UserManager extends AbstractRelationnalManager
{
}

When connectionName is omitted, the manager uses the factory default connection. Camel-case property names are mapped to snake-case database fields unless dbFieldName is explicitly set.

Configure factories

<?php

declare(strict_types=1);

use Small\SwooleEntityManager\Factory\ConnectionFactory;
use Small\SwooleEntityManager\Factory\EntityManagerFactory;

$connectionFactory = new ConnectionFactory(
    config: [
        'default' => [
            'type' => 'mysql',
            'host' => 'mysql',
            'port' => '3306',
            'database' => 'app',
            'user' => 'app',
            'password' => 'secret',
            'encoding' => 'utf8mb4',
            'maxConnections' => 50,
        ],
    ],
    defaultConnection: 'default',
);

$entityManagerFactory = new EntityManagerFactory($connectionFactory);

MySQL defaults to port 3306; PostgreSQL defaults to port 5432. maxConnections is optional.

Insert, read, update and delete

<?php

use App\Entity\UserEntity;
use App\EntityManager\UserManager;

/** @var UserManager $userManager */
$userManager = $entityManagerFactory->get(UserManager::class);

/** @var UserEntity $user */
$user = $userManager->newEntity();
$user->setUsername('nadia');
$user->persist();

$loaded = $userManager->findOneBy(['id' => $user->getId()]);
$loaded->setUsername('Nadia');
$loaded->persist();
$loaded->delete();

persist() inserts a new entity when it was not loaded from the database, and updates it otherwise. findBy() returns an EntityCollection; findOneBy() requires exactly one result and throws for zero or multiple rows.

Next chapter: Entities and fields