sebk69

Posted on Aug 25

Small Entity Schema 2: Visual Modelling for Small Swoole Entity Manager

#php #swoole #openswoole #opensource

Small Entity Schema started as a utility for generating and updating entities used by Small Swoole Entity Manager.

Version 2 takes a much larger step: it is now a real Linux desktop application for exploring an existing PHP project, modelling its entities visually, editing ORM metadata and writing the result back to the PHP source.

The objective is not to replace PHP code with a visual designer.

The objective is to make the structural part of an ORM model easier to understand and maintain, while keeping the business code under developer control.

From PHP classes to a visual entity graph

Once a project is selected, Small Entity Schema discovers the ORM entities available through its Composer configuration and displays them as a graph.

Each entity exposes its properties and types, while relations are rendered directly between the corresponding classes.

This becomes particularly useful when an application grows beyond a handful of entities.

Instead of mentally reconstructing the domain model by jumping between PHP files, you can inspect the relationships from one workspace.

The canvas supports entity movement, panning and automatic arrangement, making it possible to reorganize even relatively large schemas.

Relations are routed around entities, and link crossings are represented visually to keep complex diagrams readable.

Edit entities without leaving the graph

An entity can be selected directly from the workspace and edited from the inspector.

The editor manages the ORM-oriented parts of the class:

class name and namespace;
properties and scalar types;
primary keys;
fields;
ToOne relations;
ToMany relations;
collection metadata;
Small Forms metadata.

The important distinction is that Small Entity Schema does not own the complete PHP class.

It owns the schema.

Your application still owns its behaviour.

Source-aware PHP generation

A visual entity designer becomes dangerous very quickly if every update rewrites the complete class.

Small Entity Schema uses a different approach.

When updating an existing entity, it modifies the structures it manages while preserving code that belongs to the application.

Custom methods, method bodies, interfaces, PHPDoc, non-ORM properties and unrelated PHP attributes remain intact.

This means an entity can continue to contain real domain behaviour instead of becoming a generated DTO that developers are afraid to edit.

After changing the schema, Update source code writes the corresponding ORM attributes back to the project.

The resulting PHP source remains the canonical representation of the model.

The visual editor is a tool around the source code, not a replacement for it.

Small Forms integration

Small Entity Schema 2 can also manage metadata from Small Forms.

This makes it possible to keep persistence metadata and form/input constraints close to the same domain property.

For a property, the editor can configure the Small Forms type as well as validation and transformation metadata.

For example, an ORM field can also carry constraints such as email validation, non-empty validation or transformation rules.

The generated attributes are written directly beside the ORM declaration, so the resulting class remains explicit and readable from PHP.

This also makes Small Entity Schema useful beyond database modelling: the schema can describe how data is persisted and how incoming values are interpreted and validated.

Namespace management

Namespaces can also be managed from the application.

The namespace tree is used when creating and moving entities, reducing the amount of repetitive class and directory manipulation required when reorganizing a model.

Multiple projects

Version 2 is no longer tied to a single working directory.

Small Entity Schema maintains a small SQLite project registry and exposes a native Set project menu.

Known projects can be reopened directly, and the last project is restored when the application starts.

Changing projects resets the active environment and reloads the entities from the newly selected Composer project.

Diagram positions are isolated by project, so the layout of one application does not interfere with another.

This was an important change for making Small Entity Schema a real development tool rather than a project-specific utility.

A desktop application without a local web server

The UI is implemented with Svelte and runs inside Electron, while the schema operations remain implemented in PHP.

There is deliberately no local HTTP application involved.

The renderer communicates with Electron through a restricted preload bridge. Electron then executes the packaged PHP backend and exchanges JSON over stdin/stdout.

No HTTP server is started and no localhost TCP port is required.

The AppImage contains the desktop UI, backend application, Composer dependencies and the PHP runtime required to execute the schema operations.

This gives the project a desktop UX while keeping the entity manipulation logic in PHP.

Designed for Small Swoole Entity Manager 3

Small Entity Schema 2 targets the current generation of the ORM:

small/swoole-entity-manager-core 3.x

The application understands the PHP attributes used to describe entities, primary keys, fields and relations and can reconstruct the visual representation directly from existing source code.

That bidirectional workflow is important:

PHP source → visual schema → edited schema → PHP source

Small Entity Schema is therefore useful both for creating a model and for understanding an application that already exists.

Current quality baseline

The project now has automated backend and frontend tests, static analysis, application builds and end-to-end validation.

The backend test suite currently enforces 100% class, method and line coverage.

For a source-modifying tool, this is more than a vanity metric: regressions in parsing or generation can modify real application files, so deterministic behaviour and strong regression testing matter.

Try Small Entity Schema

Small Entity Schema is open source under the MIT license.

The current released version is 2.0.1.

Complete documentation

https://swoole-entity-manager.small-project.dev/entity-schema/

Small Swoole Entity Manager documentation:

https://swoole-entity-manager.small-project.dev/

After downloading:

chmod +x small-entity-schema-v2.0.1.AppImage
./small-entity-schema-v2.0.1.AppImage

If FUSE 2 is not available:

APPIMAGE_EXTRACT_AND_RUN=1 ./small-entity-schema-v2.0.1.AppImage

Small Entity Schema is still evolving, but the direction is now clear: provide a practical visual layer over PHP entity modelling without taking ownership away from the source code.

If you are already using Small Swoole Entity Manager, I would be interested in feedback about the workflow, relation visualization and which schema operations should be added next.

php #swoole #openswoole #opensource

DEV Community