Download the PHP package kdevhubin/pdoentitygenerator without Composer

PDO Entity Generator

A CLI tool to generate PHP PDO Entity and Repository classes from database tables. Works in any PHP project — no framework required.

Table of Contents

• Requirements
• Getting Started
  • Installation
  • Configuration
  • Quick Start
• Usage
  • Generating Entities
  • Generated Entity Example
  • Generated Repository Example
  • Generated PdoFactory
  • Using Generated Classes
• Reference
  • Configuration Options
  • Naming Conventions
  • Type Mapping
• Architecture
• Contributing
  • Development Setup
  • Project Structure
  • Coding Standards
  • Adding a New SQL Type Mapping
  • Modifying Generated Code Templates
  • Testing Changes Locally
  • Submitting Changes
• Troubleshooting
• Licence

Requirements

• PHP 8.4 or higher
• PDO extension (ext-pdo)
• MySQL / MariaDB database
• Composer 2.x

Getting Started

Installation

Install the package via Composer:

This package is a Composer Plugin. On first install, Composer will prompt you to allow the plugin:

Type y to allow it. You can also pre-authorise the plugin by adding it to your project's composer.json:

Once allowed, the plugin automatically creates config/pdoentitygenerator.yaml with default settings. There is no manual setup step required.

Configuration

Open config/pdoentitygenerator.yaml in your project root and update it with your database credentials:

Important: The database.dbname field is required. The generator will not run without it.

Quick Start

Usage

Generating Entities

Run the CLI command with the table subcommand followed by the database table name:

The tool will:

1. Read config/pdoentitygenerator.yaml for database connection details
2. Connect to the database via PDO
3. Inspect the table schema (column names, types, nullability)
4. Generate an Entity class, a Repository class, and a PdoFactory class in the configured output directories

Example

This generates:

• src/Entity/TestMyTable.php — POPO with typed properties, getters, and setters
• src/Repository/TestMyTableRepository.php — PDO-based CRUD repository
• src/Factory/PdoFactory.php — framework-agnostic factory for creating configured PDO connections (skipped if already exists)

Generated Entity Example

For a table test_my_table with columns id, name, email, and created_at:

Generated Repository Example

CRUD Methods

All queries use prepared statements with bindValue() and explicit PDO::PARAM_* type constants to enforce data types and prevent SQL injection.

Generated PdoFactory

The generator also creates a PdoFactory class that reads your database credentials from config/pdoentitygenerator.yaml and returns a configured PDO instance. Uses a singleton pattern — subsequent calls to create() return the same connection, avoiding redundant connections. Call reset() to force a new connection. This is framework-agnostic and works in any PHP project.

Plain PHP Usage

Symfony Usage (services.yaml)

Register the factory as a service to enable autowiring for all repositories:

Using Generated Classes

Reference

Configuration Options

Naming Conventions

The generator automatically converts between database snake_case and PHP naming conventions:

Type Mapping

Architecture

How It Works

1. CLI Entry Point (bin/pdoentitygenerator) — Resolves the Composer autoloader and delegates to GenerateEntityCommand
2. Command (GenerateEntityCommand) — Parses argv, loads config, connects to the database, and orchestrates the generation pipeline
3. Config Loader (ConfigLoader) — Reads config/pdoentitygenerator.yaml, merges with defaults, and validates required fields
4. Table Inspector (TableInspector) — Executes DESCRIBE <table> to retrieve column metadata (name, type, nullability, primary key)
5. Entity Generator (EntityGenerator) — Produces a POPO class with typed properties, getters, setters, and snake_case→camelCase conversion
6. Repository Generator (RepositoryGenerator) — Produces a repository class with find, findAll, insert, update, delete methods using bindValue() with explicit PDO::PARAM_* type constants
7. PdoFactory Generator (PdoFactoryGenerator) — Produces a framework-agnostic factory class that reads database credentials from config/pdoentitygenerator.yaml and returns a configured PDO instance
8. Post-Install Handler (PostInstallHandler) — Composer Plugin (implements PluginInterface and EventSubscriberInterface) that subscribes to POST_INSTALL_CMD and POST_UPDATE_CMD events to auto-create config/pdoentitygenerator.yaml in the host project when the package is installed

Contributing

Development Setup

1. Clone the repository:

2. Install dependencies:

3. Set up a test database (MySQL/MariaDB):

4. Configure the tool:

   Create config/pdoentitygenerator.yaml with your test database credentials:

5. Run the generator to verify everything works:

Project Structure

Coding Standards

This project follows the PHP Coding Standards and Best Practices document. Key rules are summarised below.

General

• PHP Version: All code must target PHP 8.4+
• Strict Types: Every PHP file must declare declare(strict_types=1);
• PSR-12: Follow PSR-12 Extended Coding Style
• Line Length: Maximum 120 characters per line
• No Doctrine: This project intentionally avoids Doctrine ORM — all database interaction uses raw PDO

PHPDoc

• All classes must have a class-level PHPDoc with @package tag
• All methods must have PHPDoc with @param, @return, and @throws tags
• Document all exception types the method can throw, including those from called methods

Imports and Namespaces

• All classes use the kdevhub\PdoEntityGenerator\ namespace
• Replace Fully Qualified Names (FQN) with use import statements (e.g. use RuntimeException; instead of \RuntimeException)
• Alphabetise import statements
• Remove unused imports

Class Structure

• Mark classes as final unless they are designed for extension
• Declare visibility on all properties, methods, and constants (public, protected, private)
• Order class members: constants → properties → constructor → public methods → protected methods → private methods

PHP 8.4 Features

• Constructor Promotion: Use constructor property promotion where appropriate
• Readonly Properties: Use readonly for properties that should not change after construction
• Match Expressions: Prefer match over switch for value-based branching
• Typed Constants: Use typed constants (const string, const array)

Strings and Arrays

• Use single quotes for strings without variable interpolation
• Use {$variable} syntax for complex interpolation in double-quoted strings
• Use short array syntax ([]) with trailing commas in multiline arrays

Best Practices

• Use early returns (guard clauses) to reduce nesting — maximum 3–4 levels of indentation
• Use named constants instead of magic numbers or strings
• Use dependency injection — avoid new inside classes for dependencies
• All database queries must use parameterised prepared statements

Adding a New SQL Type Mapping

To add support for a new SQL data type:

1. Open src/Database/TableInspector.php

2. Add the mapping to the TYPE_MAP constant:

3. If the type requires special handling in generated code (e.g. custom hydration or parameter binding), update the corresponding match expressions in:
   • src/Generator/RepositoryGenerator.php → buildHydrateBody() for reading from DB
   • src/Generator/RepositoryGenerator.php → buildBindValueLine() for writing to DB
   • src/Generator/RepositoryGenerator.php → resolvePdoParamType() if a new PDO parameter type is needed

Modifying Generated Code Templates

The generated Entity and Repository code is built using PHP heredoc templates within the generator classes:

• Entity template: src/Generator/EntityGenerator.php → buildClassTemplate(), buildGetter(), buildSetter()
• Repository template: src/Generator/RepositoryGenerator.php → generate(), buildInsertMethod(), buildUpdateMethod(), buildHydrateBody()
• PdoFactory template: src/Generator/PdoFactoryGenerator.php → generate()

When modifying templates:

• Pay close attention to heredoc indentation — the closing marker's position determines the base indent level
• Variable interpolation within heredocs uses {$variable} syntax
• Escape $ with \$ when the dollar sign should appear in generated output
• Test with tables containing various column types (int, varchar, datetime, boolean) to verify output

Testing Changes Locally

After making changes, verify the generator produces valid output:

Submitting Changes

1. Create a feature branch from test-generator:

2. Make your changes and verify generated output
3. Ensure all PHPDoc comments are complete with @param, @return, and @throws tags
4. Verify imports are alphabetised and no FQNs are used in code
5. Commit with a descriptive message
6. Push and create a pull request targeting test-generator

Troubleshooting

"Configuration file not found" error

The config/pdoentitygenerator.yaml file was not created during installation. This usually happens when the Composer Plugin was not allowed. Either:

1. Re-run composer install and type y when prompted to trust the plugin, or
2. Manually create the file:

Then create config/pdoentitygenerator.yaml with the contents shown in the Configuration section.

"Database name must be specified" error

The database.dbname field in config/pdoentitygenerator.yaml is empty or missing. Update it with your database name.

"Database connection failed" error

Verify your database credentials in config/pdoentitygenerator.yaml. Ensure:

• The database server is running
• The host, port, username, and password are correct
• The specified database exists
• The PDO driver matches your database (e.g. mysql for MySQL/MariaDB)

"Table not found or has no columns" error

The specified table does not exist in the configured database. Check:

• The table name is spelled correctly (case-sensitive)
• You are connected to the correct database

Generated files have incorrect namespace

Update the output.entity_namespace, output.repository_namespace, and output.factory_namespace values in config/pdoentitygenerator.yaml to match your project's PSR-4 autoload configuration.

Licence

This project is licensed under the MIT Licence — see the LICENSE file for details.